\input ../texinfo
XEmacs Manual
July 1994 (General Public License upgraded, January 1991)
Richard Stallman
and
Lucid, Inc. Copyright (C) 1985, 1986, 1988 Richard M. Stallman.
Copyright (C) 1991, 1992, 1993, 1994 Lucid, Inc.
Copyright (C) 1993, 1994 Sun Microsystems, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "The GNU Manifesto", "Distribution" and "GNU General Public License" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the sections entitled "The GNU Manifesto", "Distribution" and "GNU General Public License" may be included in a translation approved by the author instead of in the original English.
This manual documents the use and simple customization of the Emacs editor. The reader is not expected to be a programmer to use this editor, and simple customizations do not require programming skills either. Users who are not interested in customizing Emacs can ignore the scattered customization hints.
This document is primarily a reference manual, but it can also be used as a primer. However, if you are new to Emacs, consider using the on-line, learn-by-doing tutorial, which you get by running Emacs and typing C-h t. With it, you learn Emacs by using Emacs on a specially designed file which describes commands, tells you when to try them, and then explains the results you see. Using the tutorial gives a more vivid introduction than the printed manual.
On first reading, just skim chapters one and two, which describe the notational conventions of the manual and the general appearance of the Emacs display screen. Note which questions are answered in these chapters, so you can refer back later. After reading chapter four you should practice the commands there. The next few chapters describe fundamental techniques and concepts that are used constantly. You need to understand them thoroughly, experimenting with them if necessary.
To find the documentation on a particular command, look in the index. Keys (character commands) and command names have separate indexes. There is also a glossary, with a cross reference for each term.
This manual comes in two forms: the published form and the Info form. The Info form is for on-line perusal with the INFO program; it is distributed along with GNU Emacs. Both forms contain substantially the same text and are generated from a common source file, which is also distributed along with GNU Emacs.
GNU Emacs is a member of the Emacs editor family. There are many Emacs editors, all sharing common principles of organization. For information on the underlying philosophy of Emacs and the lessons learned from its development, write for a copy of AI memo 519a, "Emacs, the Extensible, Customizable Self-Documenting Display Editor", to Publications Department, Artificial Intelligence Lab, 545 Tech Square, Cambridge, MA 02139, USA. At last report they charge $2.25 per copy. Another useful publication is LCS TM-165, "A Cookbook for an Emacs", by Craig Finseth, available from Publications Department, Laboratory for Computer Science, 545 Tech Square, Cambridge, MA 02139, USA. The price today is $3.
This manual is for GNU Emacs installed on UNIX systems. GNU Emacs can also be used on VMS systems, which have different file name syntax and don't support all GNU Emacs features. A VMS edition of this manual may appear in the future.
Copyright (C) 1989 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too.
When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
The precise terms and conditions for copying, distribution and modification follow.
If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and a brief idea of what it does. Copyright (C) 19yy name of author This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice
That's all there is to it!
XEmacs is free; this means that everyone is free to use it and free to redistribute it on a free basis. XEmacs is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GNU Emacs that they might get from you. The precise conditions are found in the GNU General Public License that comes with Emacs and also appears following this section.
The easiest way to get a copy of GNU Emacs is from someone else who has it. You need not ask for permission to do so, or tell any one else; just copy it.
If you have access to the Internet, you can get the latest version of XEmacs from anonymous FTP server, `cs.uiuc.edu'. It can also be found at numerous other archive sites around the world; check the file `etc/DISTRIB' in a XEmacs distribution for the latest known list.
XEmacs, the version of Emacs described in this manual, is not distributed by the Free Software Foundation. You can, however, still get other versions of Emacs from there.
If you have access to the Internet, you can get the latest distribution version of GNU Emacs from host `prep.ai.mit.edu' using anonymous login. See the file `/pub/gnu/GNUinfo/FTP' on that host to find out about your options for copying and which files to use.
You may also receive GNU Emacs when you buy a computer. Computer manufacturers are free to distribute copies on the same terms that apply to everyone else. These terms require them to give you the full sources, including whatever changes they may have made, and to permit you to redistribute the GNU Emacs received from them under the usual terms of the General Public License. In other words, the program must be free for you when you get it, not just free for the manufacturer.
If you cannot get a copy in any of those ways, you can order one from the Free Software Foundation. Though Emacs itself is free, the Free Software Foundation's distribution service is not. An order form is included in the file `etc/DISTRIB' in the Emacs distribution. For further information, write to:
Free Software Foundation 675 Mass Ave. Cambridge, MA 02139 USA
The income from distribution fees goes to support the foundation's purpose: the development of more free software to distribute just like GNU Emacs.
If you find GNU Emacs useful, please send a donation to the Free Software Foundation. This will help support development of the rest of the GNU system, and other useful software beyond that. Your donation is tax deductible.
You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible real-time display editor Emacs. (The `G' in `GNU' is not silent.)
We say that Emacs is a display editor because normally the text being edited is visible on the screen and is updated automatically as you type. See section The Emacs Screen.
We call Emacs a real-time editor because the display is updated very frequently, usually after each character or pair of characters you type. This minimizes the amount of information you must keep in your head as you edit. See section Basic Editing Commands.
We call Emacs advanced because it provides facilities that go beyond simple insertion and deletion: filling of text; automatic indentation of programs; viewing two or more files at once; and dealing in terms of characters, words, lines, sentences, paragraphs, and pages, as well as expressions and comments in several different programming languages. It is much easier to type one command meaning "go to the end of the paragraph" than to find that spot with simple cursor keys.
Self-documenting means that at any time you can type a special character, Control-h, to find out what your options are. You can also use C-h to find out what a command does, or to find all the commands relevant to a topic. See section Help.
Customizable means you can change the definitions of Emacs commands. For example, if you use a programming language in which comments start with `<**' and end with `**>', you can tell the Emacs comment manipulation commands to use those strings (see section Manipulating Comments). Another sort of customization is rearrangement of the command set. For example, you can set up the four basic cursor motion commands (up, down, left and right) on keys in a diamond pattern on the keyboard if you prefer. See section Customization.
Extensible means you can go beyond simple customization and write entirely new commands, programs in the Lisp language to be run by Emacs's own Lisp interpreter. Emacs is an "on-line extensible" system: it is divided into many functions that call each other. You can redefine any function in the middle of an editing session and replace any part of Emacs without making a separate copy of all of Emacs. Most of the editing commands of Emacs are written in Lisp; the few exceptions could have been written in Lisp but are written in C for efficiency. Only a programmer can write an extension to Emacs, but anybody can use it afterward.
The terminology used here reflects the fact that Emacs was developed on environments that had only one window, which took up the entire screen.
Each Emacs screen displays a variety of information:
You can subdivide the Emacs screen into multiple text windows, and use each window for a different file (see section Multiple Windows). Multiple Emacs windows are tiled vertically on the Emacs screen. The upper Emacs window is separated from the lower window by its mode line.
When there are multiple, tiled Emacs windows on a single Emacs screen, the Emacs window receiving input from the keyboard has the keyboard focus and is called the selected window. The selected window contains the cursor, which indicates the insertion point. If you are working in an environment that permits multiple Emacs screens, and you move the focus from one Emacs screen into another, the selected window is the one that was last selected in that screen.
The same text can be displayed simultaneously in several Emacs windows, which can be in different Emacs screens. If you alter the text in an Emacs buffer by editing it in one Emacs window, the changes are visible in all Emacs windows containing that buffer.
When Emacs is running, the cursor shows the location at which editing commands will take effect. This location is called point. You can use keystrokes or the mouse cursor to move point through the text and edit the text at different places.
While the cursor appears to point at a character, you should think of point as between two characters: it points before the character on which the cursor appears. Sometimes people speak of "the cursor" when they mean "point," or speak of commands that move point as "cursor motion" commands.
Each Emacs screen has only one cursor. When output is in progress, the cursor must appear where the typing is being done. This does not mean that point is moving. It is only that Emacs has no way to show you the location of point except when the terminal is idle.
If you are editing several files in Emacs, each file has its own point location. A file that is not being displayed remembers where point is. Point becomes visible at the correct location when you look at the file again.
When there are multiple text windows, each window has its own point location. The cursor shows the location of point in the selected window. The visible cursor also shows you which window is selected. If the same buffer appears in more than one window, point can be moved in each window independently.
The term `point' comes from the character `.', which was the command in TECO (the language in which the original Emacs was written) for accessing the value now called `point'.
The line at the bottom of the screen (below the mode line) is the echo area. Emacs uses this area to communicate with the user:
Each text window's last line is a mode line which describes what is going on in that window. When there is only one text window, the mode line appears right above the echo area. The mode line is in inverse video if the terminal supports that, starts and ends with dashes, and contains text like `Emacs: something'.
If a mode line has something else in place of `Emacs: something', the window above it is in a special subsystem such as Dired. The mode line then indicates the status of the subsystem.
Normally, the mode line has the following appearance:
--ch-Emacs: buf (major minor)----pos------
This gives information about the buffer being displayed in the window: the buffer's name, what major and minor modes are in use, whether the buffer's text has been changed, and how far down the buffer you are currently looking.
ch contains two stars (`**') if the text in the buffer has been edited (the buffer is "modified"), or two dashes (`--') if the buffer has not been edited. Exception: for a read-only buffer, it is `%%'.
buf is the name of the window's chosen buffer. The chosen buffer in the selected window (the window that the cursor is in) is also Emacs's selected buffer, the buffer in which editing takes place. When we speak of what some command does to "the buffer", we mean the currently selected buffer. See section Using Multiple Buffers.
pos tells you whether there is additional text above the top of the screen or below the bottom. If your file is small and it is completely visible on the screen, pos is `All'. Otherwise, pos is `Top' if you are looking at the beginning of the file, `Bot' if you are looking at the end of the file, or `nn%', where nn is the percentage of the file above the top of the screen.
major is the name of the major mode in effect in the buffer. At any time, each buffer is in one and only one major mode. The available major modes include Fundamental mode (the least specialized), Text mode, Lisp mode, and C mode. See section Major Modes, for details on how the modes differ and how you select one.
minor is a list of some of the minor modes that are turned on
in the window's chosen buffer. For example, `Fill' means that Auto
Fill mode is on. Abbrev means that Word Abbrev mode is on.
Ovwrt means that Overwrite mode is on. See section Minor Modes, for more
information. `Narrow' means that the buffer being displayed has
editing restricted to only a portion of its text. This is not really a
minor mode, but is like one. See section Narrowing. Def means that a
keyboard macro is being defined. See section Keyboard Macros.
Some buffers display additional information after the minor modes. For example, Rmail buffers display the current message number and the total number of messages. Compilation buffers and Shell mode display the status of the subprocess.
If Emacs is currently inside a recursive editing level, square brackets (`[...]') appear around the parentheses that surround the modes. If Emacs is in one recursive editing level within another, double square brackets appear, and so on. Since information on recursive editing applies to Emacs in general and not to any one buffer, the square brackets appear in every mode line on the screen or not in any of them. See section Recursive Editing Levels.
Emacs can optionally display the time and system load in all mode lines. To enable this feature, type M-x display-time. The information added to the mode line usually appears after the file name, before the mode names and their parentheses. It looks like this:
hh:mmpm l.ll [d]
(Some fields may be missing if your operating system cannot support them.) hh and mm are the hour and minute, followed always by `am' or `pm'. l.ll is the average number of running processes in the whole system recently. d is an approximate index of the ratio of disk activity to CPU activity for all users.
The word `Mail' appears after the load level if there is mail for you that you have not read yet.
Customization note: the variable mode-line-inverse-video
controls whether the mode line is displayed in inverse video (assuming
the terminal supports it); nil means no inverse video. The
default is t. For X screens, simply set the foreground and
background colors appropriately.
XEmacs can be used with the X Window System and a window manager like MWM or TWM. In that case, the X window manager opens, closes, and resizes Emacs screens. You use the window manager's mouse gestures to perform the operations. Consult your window manager guide or reference manual for information on manipulating X windows.
When you are working under X, each X window (that is, each Emacs screen) has a menu bar for mouse-controlled operations (see section XEmacs Pull-down Menus).
Emacs under X is also a multi-screen Emacs. You can use the New Screen menu item from the File menu to create a new Emacs screen in a new X window from the same process. The different screens will share the same buffer list, but you can look at different buffers in the different screens.
The function find-file-other-screen is just like find-file,
but picks a new screen to display the buffer in first. If there is only
one screen, then a new screen is created; otherwise some other screen
is used. This is normally bound to C-x 5 C-f, and is what
the Open File, New Screen menu item does.
The function switch-to-buffer-other-screen is just
like switch-to-buffer, but picks a new screen to display the
buffer in first. If there is only one screen, then a new screen is created;
otherwise some other screen is used. This is normally bound to
C-x 5 b.
You can specify a different default screen size other than the one
provided. Use the variable default-screen-alist, which is an
alist of default values for screen creation other than the first one.
These may be set in your init file, like this:
(setq default-screen-alist '((width . 80) (height . 55)))
For values specific to the first Emacs screen, you must use X resources.
The variable x-screen-defaults takes an alist of default screen
creation parameters for X window screens. These override what is
specified in `~/.Xdefaults' but are overridden by the arguments to
the particular call to x-create-screen.
When you create a new screen, the variable create-screen-hook
is called with one argument, the screen just created.
If you want to close one or more of the X windows you created using New Screen, use the Delete Screen menu item from the File menu.
If you are working with multiple screens, some special information applies:
screen-title-format and
screen-icon-title-format determine the title of the screen and the
title of the icon that results if you shrink the screen.
auto-lower-screen and
auto-raise-screen position a screen. If true,
auto-lower-screen lowers a screen to the bottom when it is no longer
selected. If true, auto-raise-screen raises a screen to
the top when it is selected. Under X, most ICCCM-compliant window managers
will have options to do this for you, but these variables are provided in
case you are using a broken window manager.
This chapter discusses the character set Emacs uses for input commands
and inside files. You have already learned that the more frequently
used Emacs commands are bound to keys. For example, Control-f is
bound to forward-char. The following issues are covered:
You will also learn how to customize existing key bindings and create new ones.
Earlier versions of GNU Emacs used only the ASCII character set, which defines 128 different character codes. Some of these codes are assigned graphic symbols like `a' and `='; the rest are control characters, such as Control-a (also called C-a). C-a means you hold down the CTRL key and then press a.
Keybindings in XEmacs are no longer restricted to the set of keystrokes that can be represented in ASCII. Emacs can now tell the difference between, for example, Control-h, Control-Shift-h, and Backspace.
A keystroke is like a piano chord: you get it by simultaneously striking several keys. To be more precise, a keystroke consists of a possibly empty set of modifiers followed by a single keysym. The set of modifiers is small; it consists of Control, Meta, Super, Hyper, and Shift.
The rest of the keys on your keyboard, along with the mouse buttons, make up the set of keysyms. A keysym is usually what is printed on the keys on your keyboard. Here is a table of some of the symbolic names for keysyms:
Use the variable keyboard-translate-table only if you are on a
dumb tty, as it cannot handle input that cannot be represented as ASCII.
The value of this variable is a string used as a translate table for
keyboard input or nil. Each character is looked up in this
string and the contents used instead. If the string is of length
n, character codes N and up are untranslated. If you are
running Emacs under X, you should do the translations with the
xmodmap program instead.
XEmacs represents keystrokes as lists. Each list consists of
an arbitrary combination of modifiers followed by a single keysym at the
end of the list. If the keysym corresponds to an ASCII character, you
can use its character code. (A keystroke may also be represented by an
event object, as returned by the read-key-sequence function;
non-programmers need not worry about this.)
The following table gives some examples of how to list representations for keystrokes. Each list consists of sets of modifiers followed by keysyms:
A complete key sequence is a sequence of keystrokes that Emacs understands as a unit. Key sequences are significant because you can bind them to commands. Note that not all sequences of keystrokes are possible key sequences. In particular, the initial keystrokes in a key sequence must make up a prefix key sequence.
Emacs represents a key sequence as a vector of keystrokes. Thus, the schematic representation of a complete key sequence is as follows:
[(modifier .. modifer keysym) ... (modifier .. modifier keysym)]
Here are some examples of complete key sequences:
A prefix key sequence is the beginning of a series of longer sequences that are valid key sequences; adding any single keystroke to the end of a prefix results in a valid key sequence. For example, control-x is standardly defined as a prefix. Thus there is a two-character key sequence starting with C-x for each valid keystroke, giving numerous possibilities. Here are some samples:
Adding one character to a prefix key does not have to form a complete key. It could make another, longer prefix. For example, [(control x) (\4)] is itself a prefix that leads to any number of different three-character keys, including [(control x) (\4) (f)], [(control x) (\4) (b)] and so on. It would be possible to define one of those three-character sequences as a prefix, creating a series of four-character keys, but we did not define any of them this way.
By contrast, the two-character sequence [(control f) (control k)] is not a key, because the (control f) is a complete key sequence in itself. You cannot give [(control f (control k)] an independent meaning as a command while (control f) is a complete sequence, because Emacs would understand C-f C-k as two commands.
The predefined prefix key sequences in Emacs are (control c), (control x), (control h), [(control x) (\4)], and escape. You can customize Emacs and could make new prefix keys or eliminate the default key sequences. See section Customizing Key Bindings. For example, if you redefine (control f) as a prefix, [(control f) (control k)] automatically becomes a valid key sequence (complete, unless you define it as a prefix as well). Conversely, if you remove the prefix definition of [(control x) (\4)], [(control x) (\4) (f)] (or [(control x) (\4) anything]) is no longer a valid key sequence.
Note that the above paragraphs uses \4 instead of simply 4, because \4 is the symbol whose name is "4", and plain 4 is the integer 4, which would have been interpreted as the ASCII value. Another way of representing the symbol whose name is "4" is to write ?4, which would be interpreted as the number 52, which is the ASCII code for the character "4". We could therefore actually have written 52 directly, but that is far less clear.
[(control c) (control c)]
[(meta control c)]
If there is no META key, you can still type Meta characters using two-character sequences starting with ESC. To enter M-a, you could type ESC a. To enter C-M-a, you would type ESC C-a. ESC is allowed on terminals with Meta keys, too, in case you have formed a habit of using it.
If you are running under X and do not have a META key, it is possible to reconfigure some other key to be a META key. See section Assignment of the SUPER and HYPER Keys.
Emacs believes the terminal has a META key if the variable
meta-flag is non-nil. Normally this is set automatically
according to the termcap entry for your terminal type. However, sometimes
the termcap entry is wrong, and then it is useful to set this variable
yourself. See section Variables, for how to do this.
Note: If you are running under the X window system, the setting of
the meta-flag variable is irrelevant.
Most keyboards do not, by default, have SUPER or HYPER
modifier keys. Under X, you can simulate the SUPER or
HYPER key if you want to bind keys to sequences using super
and hyper. You can use the xmodmap program to do this.
For example, to turn your CAPS-LOCK key into a SUPER key, do the following:
Create a file called ~/.xmodmap. In this file, place the lines
remove Lock = Caps_Lock keysym Caps_Lock = Super_L add Mod2 = Super_L
The first line says that the key that is currently called Caps_Lock
should no longer behave as a "lock" key. The second line says that
this should now be called Super_L instead. The third line says that
the key called Super_L should be a modifier key, which produces the
Mod2 modifier.
To create a META or HYPER key instead of a SUPER key,
replace the word Super above with Meta or Hyper.
Just after you start up X, execute the command xmodmap /.xmodmap.
You can add this command to the appropriate initialization file to have
the command executed automatically.
If you have problems, see the documentation for the xmodmap
program. The X keyboard model is quite complicated, and explaining
it is beyond the scope of this manual. However, we reprint the
following description from the X Protocol document for your convenience:
A list of keysyms is associated with each keycode. If that list
(ignoring trailing NoSymbol entries) is a single keysym `K',
then the list is treated as if it were the list
"K NoSymbol K NoSymbol". If the list (ignoring trailing
NoSymbol entries) is a pair of keysyms `K1 K2', then the
list is treated as if it were the list "K1 K2 K1 K2". If the
list (ignoring trailing NoSymbol entries) is a triple of keysyms
`K1 K2 K3', then the list is treated as if it were the list
"K1 K2 K3 NoSymbol".
The first four elements of the list are split into two groups of keysyms. Group 1 contains the first and second keysyms; Group 2 contains third and fourth keysyms. Within each group, if the second element of the group is NoSymbol, then the group should be treated as if the second element were the same as the first element, except when the first element is an alphabetic keysym `K' for which both lowercase and uppercase forms are defined. In that case, the group should be treated as if the first element were the lowercase form of `K' and the second element were the uppercase form of `K'.
The standard rules for obtaining a keysym from a KeyPress event make use of only the Group 1 and Group 2 keysyms; no interpretation of other keysyms in the list is given here. (That is, the last four keysyms are unused.)
Which group to use is determined by modifier state. Switching between
groups is controlled by the keysym named Mode_switch. Attach that
keysym to some keycode and attach that keycode to any one of the
modifiers Mod1 through Mod5. This modifier is called the group
modifier. For any keycode, Group 1 is used when the group modifier is
off, and Group 2 is used when the group modifier is on.
Within a group, which keysym to use is also determined by modifier
state. The first keysym is used when the Shift and Lock
modifiers are off. The second keysym is used when the Shift
modifier is on, or when the Lock modifier is on and the second
keysym is uppercase alphabetic, or when the Lock modifier is on
and is interpreted as ShiftLock. Otherwise, when the Lock
modifier is on and is interpreted as CapsLock, the state of the
Shift modifier is applied first to select a keysym,
but if that keysym is lower-case alphabetic, then the corresponding
upper-case keysym is used instead.
In addition to the above information on keysyms, we also provide the following description of modifier mapping from the InterClient Communications Conventions Manual:
X11 supports 8 modifier bits, of which 3 are pre-assigned to
Shift, Lock, and Control. Each modifier bit is
controlled by the state of a set of keys, and these sets are specified
in a table accessed by GetModifierMapping() and
SetModifierMapping().
A client needing to use one of the pre-assigned modifiers should assume
that the modifier table has been set up correctly to control these
modifiers. The Lock modifier should be interpreted as Caps
Lock or Shift Lock according to whether the keycodes in its
controlling set include XK_Caps_Lock or XK_Shift_Lock.
Clients should determine the meaning of a modifier bit from the keysyms being used to control it.
A client needing to use an extra modifier, for example Meta, should:
XK_Meta_L or XK_Meta_R, it should use that
modifier bit.
XK_Meta_L or
XK_Meta_R, it should select an unused modifier bit (one with
an empty controlling set) and:
XL_Meta_L in its set of keysyms,
add that keycode to the set for the chosen modifier, and then:
XL_Meta_R in its set of keysyms,
add that keycode to the set for the chosen modifier, and then:
Meta.
This means that the Mod1 modifier does not necessarily mean
Meta, although some applications (such as twm and emacs 18)
assume that. Any of the five unassigned modifier bits could mean
Meta; what matters is that a modifier bit is generated by a
keycode which is bound to the keysym Meta_L or Meta_R.
Therefore, if you want to make a META key, the right way
is to make the keycode in question generate both a Meta keysym
and some previously-unassigned modifier bit.
This section briefly discusses how characters are represented in Emacs buffers. See section Representing Key Sequences for information on representing key sequences to create key bindings.
ASCII graphic characters in Emacs buffers are displayed with their graphics. LFD is the same as a newline character; it is displayed by starting a new line. TAB is displayed by moving to the next tab stop column (usually every 8 spaces). Other control characters are displayed as a caret (`^') followed by the non-control version of the character; thus, C-a is displayed as `^A'. Non-ASCII characters 128 and up are displayed with octal escape sequences; thus, character code 243 (octal), also called M-# when used as an input character, is displayed as `\243'.
The variable ctl-arrow may be used to alter this behavior.
See section Variables Controlling Display.
This manual is full of passages that tell you what particular keys do. But Emacs does not assign meanings to keys directly. Instead, Emacs assigns meanings to functions, and then gives keys their meanings by binding them to functions.
A function is a Lisp object that can be executed as a program. Usually
it is a Lisp symbol that has been given a function definition; every
symbol has a name, usually made of a few English words separated by
dashes, such as next-line or forward-word. It also has a
definition, which is a Lisp program. Only some functions can be the
bindings of keys; these are functions whose definitions use
interactive to specify how to call them interactively. Such
functions are called commands, and their names are command
names. More information on this subject will appear in the GNU
Emacs Lisp Manual.
The bindings between keys and functions are recorded in various tables called keymaps. See section Customizing Key Bindings for more information on key sequences you can bind commands to. See section Keymaps for information on creating keymaps.
When we say "C-n moves down vertically one line" we are
glossing over a distinction that is irrelevant in ordinary use but is
vital in understanding how to customize Emacs. The function
next-line is programmed to move down vertically. C-n
has this effect because it is bound to that function. If you rebind
C-n to the function forward-word then C-n will move
forward by words instead. Rebinding keys is a common method of
customization.
The rest of this manual usually ignores this subtlety to keep
things simple. To give the customizer the information needed, we often
state the name of the command that really does the work in parentheses
after mentioning the key that runs it. For example, we will say that
"The command C-n (next-line) moves point vertically
down," meaning that next-line is a command that moves vertically
down and C-n is a key that is standardly bound to it.
While we are on the subject of information for customization only,
it's a good time to tell you about variables. Often the
description of a command will say, "To change this, set the variable
mumble-foo." A variable is a name used to remember a value.
Most of the variables documented in this manual exist just to facilitate
customization: some command or other part of Emacs uses the variable
and behaves differently depending on its setting. Until you are interested in
customizing, you can ignore the information about variables. When you
are ready to be interested, read the basic information on variables, and
then the information on individual variables will make sense.
See section Variables.
If you are running XEmacs under X, a menu bar on top of the Emacs screen provides access to pull-down menus of file, edit, and help-related commands. The menus provide convenient shortcuts and an easy interface for novice users. They do not provide additions to the functionality available via key commands; you can still invoke commands from the keyboard as in previous versions of Emacs.
There are two ways of selecting an item from a pull-down menu:
If a command in the pull-down menu is not applicable in a given situation, the command is disabled and its name appears faded. You cannot invoke items that are faded. For example, most commands on the Edit menu appear faded until you select text on which they are to operate; after you select a block of text, edit commands are enabled. See section Selecting Text with the Mouse for information on using the mouse to select text. See section Using X Selections for related information.
There are also M-x equivalents for each menu item. To find the equivalent for any left-button menu item, do the following:
Describe Key prompt.
Emacs displays the function associated with the menu item in a separate window, usually together with some documentation.
The File menu bar item contains the items New Screen, Open File..., Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete Screen, Kill Buffer and Exit Emacs on the pull-down menu. If you select a menu item, Emacs executes the equivalent command.
find-file (C-x
C-f).
insert-file (C-x i).
save-buffer (C-x C-s).
write-file (C-x C-w).
revert-file (M-x
revert-buffer).
kill-buffer (C-x k), except that kill-buffer
prompts for the name of a buffer to kill.
print-buffer (M-x print-buffer).
*scratch* buffer. This
is like the Open File, New Screen... menu item, except that it does
not prompt for or load a file.
split-window-vertically (C-x 2).
delete-other-windows (C-x 1).
delete-window
(C-x 0).
save-buffers-kill-emacs (C-x C-c). Before killing the
Emacs process, the system asks which unsaved buffers to save by going through
the list of all buffers in that Emacs process.The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and Clear menu items. When you select a menu item, Emacs executes the equivalent command. Most commands on the Edit menu work on a block of text, the X selection. They appear faded until you select a block of text (activate a region) with the mouse. See section Using X Selections, see section Deletion and Killing, and see section Yanking for more information.
undo (C-x u).
yank command, because the Emacs kill ring and the X clipboard
selection are not the same thing. You can paste in text you
have placed in the clipboard using Copy or Cut. You can also
use Paste to insert text that was pasted into the clipboard from other
applications.
start-kbd-macro (C-x ().
end-kbd-macro (C-x )).
call-last-kbd-macro (C-x e).
The Options pull-down menu contains the Read Only, Case Sensitive Search, Overstrike, Auto Delete Selection, Teach Extended Commands, Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers Menu Length..., Buffers Sub-Menus and Save Options menu items. When you select a menu item, Emacs executes the equivalent command. For some of the menu items, there are sub-menus which you will need to select.
toggle-read-only
(C-x C-q).
quoted-insert (C-q).
.emacs file to include the font-lock
mode so that when you select this item, the comments will be
displayed in one face, strings in another, reserved words in another,
and so on. When Fonts is selected, different parts of the program
will appear in different Fonts. When Colors is selected, then the
program will be displayed in different colors. Selecting None
causes the program to appear in just one Font and Color. Selecting
Less resets the Fonts and Colors to a fast, minimal set of
decorations. Selecting More resets the Fonts and Colors to a larger
set of decorations. For example, if Less is selected (which is the
default setting) then you might have all comments in green color.
Whereas, if More is selected then a function name in the comments
themselves might appear in a different Color or Font.
.emacs file.
The Help Menu gives you access to Emacs Info and provides a menu equivalent for each of the choices you have when using C-h. See section Help for more information.
The Help menu also gives access to UNIX online manual pages via the UNIX Manual Page option.
You can customize any of the pull-down menus by adding or removing menu items and disabling or enabling existing menu items. The following functions are available:
Use the function add-menu to add a new menu or submenu.
If a menu or submenu of the given name exists already, it is changed.
menu-path identifies the menu under which the new menu should be
inserted. It is a list of strings; for example, ("File") names
the top-level File menu. ("File" "Foo") names a hypothetical
submenu of File. If menu-path is nil, the menu is
added to the menu bar itself.
menu-name is the string naming the menu to be added.
menu-items is a list of menu item descriptions. Each menu item should be a vector of three elements:
t or nil to indicate whether the item is selectable
The optional argument before is the name of the menu before which the new menu or submenu should be added. If the menu is already present, it is not moved.
The function add-menu-item adds a menu item to the specified
menu, creating the menu first if necessary. If the named item already
exists, the menu remains unchanged.
menu-path identifies the menu into which the new menu item should
be inserted. It is a list of strings; for example, ("File")
names the top-level File menu. ("File" "Foo") names a
hypothetical submenu of File.
item-name is the string naming the menu item to add.
function is the command to invoke when this menu item is selected.
If it is a symbol, it is invoked with call-interactively, in the
same way that functions bound to keys are invoked. If it is a list, the
list is simply evaluated.
enabled-p controls whether the item is selectable or not.
It should be t, nil, or a form to evaluate to decide.
This form will be evaluated just before the menu is displayed, and
the menu item will be selectable if that form returns non-nil.
For example, to make the rename-file command available from the
File menu, use the following code:
(add-menu-item '("File") "Rename File" 'rename-file t)
To add a submenu of file management commands using a File Management item, use the following code:
(add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
(add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
(add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
The optional before argument is the name of a menu item before which the new item should be added. If the item is already present, it is not moved.
To remove a specified menu item from the menu hierarchy, use
delete-menu-item.
path is a list of strings that identify the position of the menu
item in the menu hierarchy. ("File" "Save") means the menu item
called Save under the top level File menu. ("Menu" "Foo"
"Item") means the menu item called Item under the Foo submenu
of Menu.
To disable a menu item, use disable-menu-item. The disabled
menu item is grayed and can no longer be selected. To make the
item selectable again, use enable-menu-item.
disable-menu-item and enable-menu-item both have the
argument path.
To change the string of the specified menu item, use
relabel-menu-item. This function also takes the argument path.
new-name is the string to which the menu item will be changed.
The usual way to invoke Emacs is to type emacs RET at the shell. To invoke XEmacs, type xemacs RET. Emacs clears the screen and then displays an initial advisory message and copyright notice. You can begin typing Emacs commands immediately afterward.
Some operating systems insist on discarding all type-ahead when Emacs starts up; they give Emacs no way to prevent this. Therefore, it is wise to wait until Emacs clears the screen before typing the first editing command.
Before Emacs reads the first command, you have not had a chance to
give a command to specify a file to edit. Since Emacs must always have a
current buffer for editing, it presents a buffer, by default, a buffer named
`*scratch*'. The buffer is in Lisp Interaction
mode; you can use it to type Lisp expressions and evaluate them, or you
can ignore that capability and simply doodle. You can specify a
different major mode for this buffer by setting the variable
initial-major-mode in your init file. See section The Init File, .emacs.
It is possible to give Emacs arguments in the shell command line to specify files to visit, Lisp files to load, and functions to call.
There are two commands for exiting Emacs because there are two kinds of exiting: suspending Emacs and killing Emacs. Suspending means stopping Emacs temporarily and returning control to its superior (usually the shell), allowing you to resume editing later in the same Emacs job, with the same files, same kill ring, same undo history, and so on. This is the usual way to exit. Killing Emacs means destroying the Emacs job. You can run Emacs again later, but you will get a fresh Emacs; there is no way to resume the same editing session after it has been killed.
suspend-emacs). If used under the X window system,
shrink the X window containing the Emacs screen to an icon (see below).
save-buffers-kill-emacs).
If you use XEmacs under the X window system, C-z shrinks the X window containing the Emacs screen to an icon. The Emacs process is stopped temporarily, and control is returned to the window manager. If more than one screen is associated with the Emacs process, only the screen from which you used C-z is retained. The X windows containing the other Emacs screens are closed.
To activate the "suspended" Emacs, use the appropriate window manager mouse gestures. Usually left-clicking on the icon reactivates and reopens the X window containing the Emacs screen, but the window manager you use determines what exactly happens. To actually kill the Emacs process, use C-x C-c or the Exit Emacs item on the File menu.
On systems that do not permit programs to be suspended, C-z runs
an inferior shell that communicates directly with the terminal, and
Emacs waits until you exit the subshell. On these systems, the only way
to return to the shell from which Emacs was started (to log out, for
example) is to kill Emacs. C-d or exit are typical
commands to exit a subshell.
To kill Emacs, type C-x C-c (save-buffers-kill-emacs). A
two-character key is used for this to make it harder to type. In
XEmacs, selecting the Exit Emacs option of the File menu is an
alternate way of issuing the command.
Unless a numeric argument is used, this command first offers to save any modified buffers. If you do not save all buffers, you are asked for reconfirmation with yes before killing Emacs, since any changes not saved will be lost. If any subprocesses are still running, C-x C-c asks you to confirm killing them, since killing Emacs kills the subprocesses simultaneously.
In most programs running on Unix, certain characters may instantly suspend or kill the program. (In Berkeley Unix these characters are normally C-z and C-c.) This Unix feature is turned off while you are in Emacs. The meanings of C-z and C-x C-c as keys in Emacs were inspired by the standard Berkeley Unix meanings of C-z and C-c, but that is their only relationship with Unix. You could customize these keys to do anything (see section Keymaps).
GNU Emacs supports command line arguments you can use to request various actions when invoking Emacs. The commands are for compatibility with other editors and for sophisticated activities. If you are using XEmacs under the X window system, you can also use a number of standard Xt command line arguments. Command line arguments are not usually needed for editing with Emacs; new users can skip this section.
Many editors are designed to be started afresh each time you want to edit. You start the editor to edit one file; then exit the editor. The next time you want to edit either another file or the same one, you start the editor again. Under these circumstances, it makes sense to use a command line argument to say which file to edit.
The recommended way to use GNU Emacs is to start it only once, just after you log in, and do all your editing in the same Emacs process. Each time you want to edit a file, you visit it using the existing Emacs. Emacs creates a new buffer for each file, and (unless you kill some of the buffers) Emacs eventually has many files in it ready for editing. Usually you do not kill the Emacs process until you are about to log out. Since you usually read files by typing commands to Emacs, command line arguments for specifying a file when Emacs is started are seldom needed.
Emacs accepts command-line arguments that specify files to visit, functions to call, and other activities and operating modes. If you are running XEmacs under the X window system, a number of standard Xt command line arguments are available as well.
The following subsections list:
Here are the arguments allowed:
find-file. See section Visiting Files.
find-file, then go to line number
linenum in it.
load.
See section Libraries of Lisp Code for Emacs.
% emacs -version GNU Emacs 19.6 Lucid of Thu Apr 1 1993 on thalidomide (berkeley-unix)
stderr only what would normally be printed
in the echo area under program control.
Batch mode is used for running programs written in Emacs Lisp from shell
scripts, makefiles, and so on. Normally the `-l' switch or
`-f' switch will be used as well, to invoke a Lisp program to do
the batch processing.
`-batch' implies `-q' (do not load an init file). It also
causes Emacs to kill itself after all command switches have been
processed. In addition, auto-saving is not done except in buffers for
which it has been explicitly requested.
Note that the init file can get access to the command line argument
values as the elements of a list in the variable
command-line-args. (The arguments in the second table above will
already have been processed and will not be in the list.) The init file
can override the normal processing of the other arguments by setting
this variable.
One way to use command switches is to visit many files automatically:
emacs *.c
passes each .c file as a separate argument to Emacs, so that
Emacs visits each file (see section Visiting Files).
Here is an advanced example that assumes you have a Lisp program file called `hack-c-program.el' which, when loaded, performs some useful operation on the current buffer, expected to be a C program.
emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
Here Emacs is told to visit `foo.c', load `hack-c-program.el'
(which makes changes in the visited file), save `foo.c' (note that
save-buffer is the function that C-x C-s is bound to), and
then exit to the shell from which the command was executed. `-batch'
guarantees there will be no problem redirecting output to `log',
because Emacs will not assume that it has a display terminal to work
with.
screen-title-format variable, which controls the title of the X
window corresponding to the selected screen. This is the same format as
mode-line-format.
screen-icon-title-format variable, which controls the title of
the icon corresponding to the selected screen.
In addition, XEmacs allows you to use a number of standard Xt command line arguments.
argv[0]) as
the resource manager name.
We now give the basics of how to enter text, make corrections, and
save the text in a file. If this material is new to you, you might
learn it more easily by running the Emacs learn-by-doing tutorial. To
do this, type Control-h t (help-with-tutorial).
To insert printing characters into the text you are editing, just type them. This inserts the characters into the buffer at the cursor (that is, at point; see section Point). The cursor moves forward. Any characters after the cursor move forward too. If the text in the buffer is `FOOBAR', with the cursor before the `B', and you type XX, the result is `FOOXXBAR', with the cursor still before the `B'.
To delete text you have just inserted, use DEL. DEL deletes the character before the cursor (not the one that the cursor is on top of or under; that is the character after the cursor). The cursor and all characters after it move backwards. Therefore, if you type a printing character and then type DEL, they cancel out.
To end a line and start typing a new one, type RET. This inserts a newline character in the buffer. If point is in the middle of a line, RET splits the line. Typing DEL when the cursor is at the beginning of a line rubs out the newline before the line, thus joining the line with the preceding line.
Emacs automatically splits lines when they become too long, if you turn on a special mode called Auto Fill mode. See section Filling Text, for information on using Auto Fill mode.
Customization information: DEL, in most modes, runs the command
delete-backward-char; RET runs the command newline,
and self-inserting printing characters run the command
self-insert, which inserts whatever character was typed to invoke
it. Some major modes rebind DEL to other commands.
Direct insertion works for printing characters and SPC, but
other characters act as editing commands and do not insert themselves.
If you need to insert a control character or a character whose code is
above 200 octal, you must quote it by typing the character
control-q (quoted-insert) first. There are two ways to use
C-q:
A numeric argument to C-q specifies how many copies of the quoted character should be inserted (see section Numeric Arguments).
If you prefer to have text characters replace (overwrite) existing text instead of moving it to the right, you can enable Overwrite mode, a minor mode. See section Minor Modes.
To do more than insert characters, you have to know how to move point (see section Point). Here are a few of the available commands.
beginning-of-line).
end-of-line).
forward-char).
backward-char).
forward-word).
backward-word).
next-line). This command attempts to keep the horizontal position unchanged, so if you start in the middle of one line, you end in the middle of the next. When on the last line of text, C-n creates a new line and moves onto it. @item C-p
Move up one line, vertically (previous-line).
recenter). Text moves
on the screen to bring point to the center of the window.
move-to-window-line). Text does not move on the
screen. A numeric argument says how many screen lines down from the
top of the window (zero for the top). A negative argument counts from
the bottom (-1 for the bottom).
transpose-chars).
beginning-of-buffer). With
numeric argument n, move to n/10 of the way from the top.
See section Numeric Arguments, for more information on numeric arguments.end-of-buffer).
set-goal-column). Henceforth, those
commands always move to this column in each line moved into, or as
close as possible given the contents of the line. This goal column remains
in effect until canceled.
If you set the variable track-eol to a non-nil value,
C-n and C-p move to the end of the line when at the end of
the starting line. By default, track-eol is nil.
delete-backward-char).
delete-char).
kill-line).
kill-word).
backward-kill-word).
In contrast to the DEL key, which deletes the character before the cursor, Control-d deletes the character after the cursor, causing the rest of the text on the line to shift left. If Control-d is typed at the end of a line, that line and the next line are joined.
To erase a larger amount of text, use Control-k, which kills a line at a time. If you use C-k at the beginning or in the middle of a line, it kills all the text up to the end of the line. If you use C-k at the end of a line, it joins that line and the next line.
See section Deletion and Killing, for more flexible ways of killing text.
The commands above are sufficient for creating and altering text in an Emacs buffer. More advanced Emacs commands just make things easier. But to keep any text permanently you must put it in a file. Files are named units of text which are stored by the operating system and which you can retrieve by name. To look at or use the contents of a file in any way, including editing the file with Emacs, you must specify the file name.
Consider a file named `/usr/rms/foo.c'. To begin editing this file from Emacs, type:
C-x C-f /usr/rms/foo.c RET
The file name is given as an argument to the command C-x
C-f (find-file). The command uses the minibuffer to
read the argument. You have to type RET to terminate the argument
(see section The Minibuffer).
You can also use the Open... menu item from the File menu, then type the name of the file to the prompt.
Emacs obeys the command by visiting the file: it creates a
buffer, copies the contents of the file into the buffer, and then
displays the buffer for you to edit. You can make changes in the
buffer, and then save the file by typing C-x C-s
(save-buffer) or choosing Save Buffer from the File menu. This
makes the changes permanent by copying the altered contents of the
buffer back into the file `/usr/rms/foo.c'. Until then, the
changes are only inside your Emacs buffer, and the file `foo.c' is
not changed.
To create a file, visit the file with C-x C-f as if it already existed or choose Open... from the File menu and provide the name for the new file in the minibuffer. Emacs will create an empty buffer in which you can insert the text you want to put in the file. When you save the buffer with C-x C-s, or by choosing Save Buffer from the File menu, the file is created.
To learn more about using files, see section File Handling.
If you forget what a key does, you can use the Help character
(C-h) to find out: Type C-h k followed by the key you want to know
about. For example, C-h k C-n tells you what C-n
does. C-h is a prefix key; C-h k is just one of its
subcommands (the command describe-key). The other subcommands of
C-h provide different kinds of help. Type C-h three times
to get a description of all the help facilities. See section Help.
Here are special commands and techniques for entering and removing blank lines.
open-line).
delete-blank-lines).
When you want to insert a new line of text before an existing line,
you just type the new line of text, followed by RET. If you
prefer to create a blank line first and then insert the desired text,
use the key C-o (open-line), which inserts a newline after
point but leaves point in front of the newline. Then type
the text into the new line. C-o F O O has the same effect as
F O O RET, except for the final location of point.
To create several blank lines, type C-o several times, or give C-o an argument indicating how many blank lines to create. See section Numeric Arguments, for more information.
If you have many blank lines in a row and want to get rid of them, use
C-x C-o (delete-blank-lines). If point is on a blank
line which is adjacent to at least one other blank line, C-x C-o
deletes all but one of the blank lines.
If point is on a blank line with no other adjacent blank line, the
sole blank line is deleted. If point is on a non-blank
line, C-x C-o deletes any blank lines following that non-blank
line.
If you add too many characters to one line without breaking with a RET, the line grows to occupy two (or more) screen lines, with a curved arrow at the extreme right margin of all but the last line. The curved arrow indicates that the following screen line is not really a distinct line in the text, but just the continuation of a line too long to fit the screen. You can use Auto Fill mode (see section Filling Text) to have Emacs insert newlines automatically when a line gets too long.
Instead of continuation, long lines can be displayed by truncation. This means that all the characters that do not fit in the width of the screen or window do not appear at all. They remain in the buffer, temporarily invisible. Three diagonal dots in the last column (instead of the curved arrow inform you that truncation is in effect.
To turn off continuation for a particular buffer, set the
variable truncate-lines to non-nil in that buffer.
Truncation instead of continuation also happens whenever horizontal
scrolling is in use, and optionally whenever side-by-side windows are in
use (see section Multiple Windows). Altering the value of truncate-lines makes
it local to the current buffer; until that time, the default value is in
effect. The default is initially nil. See section Local Variables.
If you are accustomed to other display editors, you may be surprised that Emacs does not always display the page number or line number of point in the mode line. In Emacs, this information is only rarely needed, and a number of commands are available to compute and print it. Since text is stored in a way that makes it difficult to compute the information, it is not displayed all the time.
count-lines-region).
what-cursor-position).
There are several commands for printing line numbers:
count-lines-region) prints the number of lines in
the region (see section Selecting Text).
The command C-x = (what-cursor-position) provides
information about point and about the column the cursor is in.
It prints a line in the echo area that looks like this:
Char: x (0170) point=65986 of 563027(12%) column 44
(In fact, this is the output produced when point is before `column 44' in the example.)
The two values after `Char:' describe the character following point, first by showing it and second by giving its octal character code.
`point=' is followed by the position of point expressed as a character count. The front of the buffer counts as position 1, one character later as 2, and so on. The next, larger number is the total number of characters in the buffer. Afterward in parentheses comes the position expressed as a percentage of the total size.
`column' is followed by the horizontal position of point, in columns from the left edge of the window.
If the buffer has been narrowed, making some of the text at the beginning and the end temporarily invisible, C-x = prints additional text describing the current visible range. For example, it might say:
Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> column 44
where the two extra numbers give the smallest and largest character position that point is allowed to assume. The characters between those two positions are the visible ones. See section Narrowing.
If point is at the end of the buffer (or the end of the visible part), C-x = omits any description of the character after point. The output looks like
point=563026 of 563025(100%) column 0
Any Emacs command can be given a numeric argument. Some commands
interpret the argument as a repetition count. For example, giving an
argument of ten to the key C-f (the command forward-char, move
forward one character) moves forward ten characters. With these commands,
no argument is equivalent to an argument of one. Negative arguments are
allowed. Often they tell a command to move or act backwards.
If your keyboard has a META key, the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the the META key. For example,
M-5 C-nmoves down five lines. The characters Meta-1, Meta-2, and so on, as well as Meta--, do this because they are keys bound to commands (
digit-argument and negative-argument) that are
defined to contribute to an argument for the next command.
Another way of specifying an argument is to use the C-u
(universal-argument) command followed by the digits of the argument.
With C-u, you can type the argument digits without holding
down shift keys. To type a negative argument, start with a minus sign.
Just a minus sign normally means -1. C-u works on all terminals.
C-u followed by a character which is neither a digit nor a minus sign has the special meaning of "multiply by four". It multiplies the argument for the next command by four. C-u twice multiplies it by sixteen. Thus, C-u C-u C-f moves forward sixteen characters. This is a good way to move forward "fast", since it moves about 1/5 of a line in the usual size screen. Other useful combinations are C-u C-n, C-u C-u C-n (move down a good fraction of a screen), C-u C-u C-o (make "a lot" of blank lines), and C-u C-k (kill four lines).
Some commands care only about whether there is an argument and not about
its value. For example, the command M-q (fill-paragraph) with
no argument fills text; with an argument, it justifies the text as well.
(See section Filling Text, for more information on M-q.) Just C-u is a
handy way of providing an argument for such commands.
Some commands use the value of the argument as a repeat count, but do
something peculiar when there is no argument. For example, the command
C-k (kill-line) with argument n kills n lines,
including their terminating newlines. But C-k with no argument is
special: it kills the text up to the next newline, or, if point is right at
the end of the line, it kills the newline itself. Thus, two C-k
commands with no arguments can kill a non-blank line, just like C-k
with an argument of one. (See section Deletion and Killing, for more information on
C-k.)
A few commands treat a plain C-u differently from an ordinary argument. A few others may treat an argument of just a minus sign differently from an argument of -1. These unusual cases will be described when they come up; they are always to make the individual command more convenient to use.
Emacs allows you to undo all changes you make to the text of a buffer,
up to a certain amount of change (8000 characters). Each buffer records
changes individually, and the undo command always applies to the
current buffer. Usually each editing command makes a separate entry
in the undo records, but some commands such as query-replace
make many entries, and very simple commands such as self-inserting
characters are often grouped to make undoing less tedious.
undo).
The command C-x u or C-_ allows you to undo changes. The first time you give this command, it undoes the last change. Point moves to the text affected by the undo, so you can see what was undone.
Consecutive repetitions of the C-_ or C-x u commands undo earlier and earlier changes, back to the limit of what has been recorded. If all recorded changes have already been undone, the undo command prints an error message and does nothing.
Any command other than an undo command breaks the sequence of undo commands. Starting at this moment, the previous undo commands are considered ordinary changes that can themselves be undone. Thus, you can redo changes you have undone by typing C-f or any other command that have no important effect, and then using more undo commands.
If you notice that a buffer has been modified accidentally, the easiest way to recover is to type C-_ repeatedly until the stars disappear from the front of the mode line. When that happens, all the modifications you made have been canceled. If you do not remember whether you changed the buffer deliberately, type C-_ once. When you see Emacs undo the last change you made, you probably remember why you made it. If the change was an accident, leave it undone. If it was deliberate, redo the change as described in the preceding paragraph.
Whenever an undo command makes the stars disappear from the mode line, the buffer contents is the same as it was when the file was last read in or saved.
Not all buffers record undo information. Buffers whose names start with spaces don't; these buffers are used internally by Emacs and its extensions to hold text that users don't normally look at or edit. Minibuffers, help buffers, and documentation buffers also don't record undo information.
Emacs can remember at most 8000 or so characters of deleted or modified text in any one buffer for reinsertion by the undo command. There is also a limit on the number of individual insert, delete, or change actions that Emacs can remember.
There are two keys to run the undo command, C-x u and
C-_, because on some keyboards, it is not obvious how to type
C-_. C-x u is an alternative you can type in the same
fashion on any terminal.
Emacs commands use the minibuffer to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things, depending on the command reading the argument. To edit the argument in the minibuffer, you can use Emacs editing commands.
When the minibuffer is in use, it appears in the echo area, and the cursor moves there. The beginning of the minibuffer line displays a prompt indicating what kind of input you should supply and how it will be used. The prompt is often derived from the name of the command the argument is for. The prompt normally ends with a colon.
Sometimes a default argument appears in parentheses after the colon; it, too, is part of the prompt. The default is used as the argument value if you enter an empty argument (e.g., by just typing RET). For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.
The simplest way to give a minibuffer argument is to type the text you want, terminated by RET to exit the minibuffer. To get out of the minibuffer and cancel the command that it was for, type C-g.
Since the minibuffer uses the screen space of the echo area, it can conflict with other ways Emacs customarily uses the echo area. Here is how Emacs handles such conflicts:
Sometimes the minibuffer starts out with text in it. For example, when you are supposed to give a file name, the minibuffer starts out containing the default directory, which ends with a slash. This informs you in which directory the file will be looked for if you do not specify a different one. For example, the minibuffer might start out with:
Find File: /u2/emacs/src/
where `Find File: ' is the prompt. Typing buffer.c specifies
the file
`/u2/emacs/src/buffer.c'. To find files in nearby
directories, use `..'; thus, if you type ../lisp/simple.el, the
file that you visit will be the one named
`/u2/emacs/lisp/simple.el'.
Alternatively, you can use M-DEL to kill directory names you
don't want (see section Words).
You can also type an absolute file name, one starting with a slash or a tilde, ignoring the default directory. For example, to find the file `/etc/termcap', just type the name, giving:
Find File: /u2/emacs/src//etc/termcap
Two slashes in a row are not normally meaningful in Unix file names, but they are allowed in GNU Emacs. They mean, "ignore everything before the second slash in the pair." Thus, `/u2/emacs/src/' is ignored, and you get the file `/etc/termcap'.
If you set insert-default-directory to nil, the default
directory is not inserted in the minibuffer. This way, the minibuffer
starts out empty. But the name you type, if relative, is still
interpreted with respect to the same default directory.
The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the text of an argument you are entering.
Since RET in the minibuffer is defined to exit the minibuffer, you must use C-o or C-q LFD to insert a newline into the minibuffer. (Recall that a newline is really the LFD character.)
The minibuffer has its own window, which always has space on the screen but acts as if it were not there when the minibuffer is not in use. The minibuffer window is just like the others; you can switch to another window with C-x o, edit text in other windows, and perhaps even visit more files before returning to the minibuffer to submit the argument. You can kill text in another window, return to the minibuffer window, and then yank the text to use it in the argument. See section Multiple Windows.
There are, however, some restrictions on the use of the minibuffer window. You cannot switch buffers in it--the minibuffer and its window are permanently attached. You also cannot split or kill the minibuffer window, but you can make it taller with C-x ^.
If you are in the minibuffer and issue a command that displays help text in another window, that window will be scrolled if you type M-C-v while in the minibuffer until you exit the minibuffer. This feature is helpful if a completing minibuffer gives you a long list of possible completions.
If the variable minibuffer-confirm-incomplete is t, you
are asked for confirmation if there is no known completion for the text
you typed. For example, if you attempted to visit a non-existent file,
the minibuffer might read:
Find File:chocolate_bar.c [no completions, confirm]
If you press Return again, that confirms the filename. Otherwise,
you can continue editing it.
Emacs supports recursive use of the minibuffer. However, it is easy to do this by accident (because of autorepeating keyboards, for example) and get confused. Therefore, most Emacs commands that use the minibuffer refuse to operate if the minibuffer window is selected. If the minibuffer is active but you have switched to a different window, recursive use of the minibuffer is allowed--if you know enough to try to do this, you probably will not get confused.
If you set the variable enable-recursive-minibuffers to be
non-nil, recursive use of the minibuffer is always allowed.
When appropriate, the minibuffer provides a completion facility. You type the beginning of an argument and one of the completion keys, and Emacs visibly fills in the rest, depending on what you have already typed.
When completion is available, certain keys---TAB, RET, and SPC---are redefined to complete an abbreviation present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument. ? is defined to display a list of possible completions of what you have inserted.
For example, when the minibuffer is being used by Meta-x to read the name of a command, it is given a list of all available Emacs command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional characters of the name that are implied by the ones already present in the minibuffer, and add those characters to the ones you have given.
Case is normally significant in completion because it is significant in most of the names that you can complete (buffer names,