"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/emacs/basic.texi" (23 Apr 2018, 33682 Bytes) of package /linux/misc/emacs-26.1.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "basic.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Basic Editing Commands

Here we explain the basics of how to enter text, make corrections, and save the text in a file. If this material is new to you, we suggest you first run the Emacs learn-by-doing tutorial, by typing C-h t (help-with-tutorial).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Inserting Text

You can insert an ordinary graphic character (e.g., ‘a’, ‘B’, ‘3’, and ‘=’) by typing the associated key. This adds the character to the buffer at point. Insertion moves point forward, so that point remains just after the inserted text. @xref{Point}.

To end a line and start a new one, type <RET> (newline). (The <RET> key may be labeled <Return>, or <Enter>, or with a funny-looking left-pointing arrow on your keyboard, but we refer to it as <RET> in this manual.) This command inserts a newline character into the buffer, then indents (@pxref{Indentation}) according to the major mode. If point is at the end of the line, the effect is to create a new blank line after it and indent the new line; if point is in the middle of a line, the line is split at that position. To turn off the auto-indentation, you can either disable Electric Indent mode (@pxref{Indent Convenience}) or type C-j, which inserts just a newline, without any auto-indentation.

As we explain later in this manual, you can change the way Emacs handles text insertion by turning on minor modes. For instance, the minor mode called Auto Fill mode splits lines automatically when they get too long (@pxref{Filling}). The minor mode called Overwrite mode causes inserted characters to replace (overwrite) existing text, instead of shoving it to the right. @xref{Minor Modes}.

Only graphic characters can be inserted by typing the associated key; other keys act as editing commands and do not insert themselves. For instance, <DEL> runs the command delete-backward-char by default (some modes bind it to a different command); it does not insert a literal ‘DEL’ character (ASCII character code 127).

To insert a non-graphic character, or a character that your keyboard does not support, first quote it by typing C-q (quoted-insert). There are two ways to use C-q:

To use decimal or hexadecimal instead of octal, set the variable read-quoted-char-radix to 10 or 16. If the radix is 16, the letters a to f serve as part of a character code, just like digits. Case is ignored.

A few common Unicode characters can be inserted via a command starting with C-x 8. For example, C-x 8 [ inserts which is Unicode code-point U+2018 LEFT SINGLE QUOTATION MARK, sometimes called a left single “curved quote” or “curly quote”. Similarly, C-x 8 ], C-x 8 { and C-x 8 } insert the curved quotes , and , respectively. Also, a working Alt key acts like C-x 8; e.g., A-[ acts like C-x 8 [ and inserts ‘. To see which characters have C-x 8 shorthands, type C-x 8 C-h.

Alternatively, you can use the command C-x 8 <RET> (insert-char). This prompts for the Unicode name or code-point of a character, using the minibuffer. If you enter a name, the command provides completion (@pxref{Completion}). If you enter a code-point, it should be as a hexadecimal number (the convention for Unicode), or a number with a specified radix, e.g., #o23072 (octal); See Integer Basics in The Emacs Lisp Reference Manual. The command then inserts the corresponding character into the buffer.

For example, the following all insert the same character:

C-x 8 <RET> left single quotation mark <RET>
C-x 8 <RET> left sin <TAB> <RET>
C-x 8 <RET> 2018 <RET>
C-x 8 [
A-[  (if the Alt key works)
`    (in Electric Quote mode)

A numeric argument to C-q or C-x 8 ... specifies how many copies of the character to insert (see section Numeric Arguments).

In addition, in some contexts, if you type a quotation using grave accent and apostrophe ‘like this’, it is converted to a form ‘like this’ using single quotation marks, even without C-x 8 commands. Similarly, typing a quotation “like this” using double grave accent and apostrophe converts it to a form “like this” using double quotation marks. @xref{Quotation Marks}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Changing the Location of Point

To do more than insert characters, you have to know how to move point (@pxref{Point}). The keyboard commands C-f, C-b, C-n, and C-p move point to the right, left, down, and up, respectively. You can also move point using the arrow keys present on most keyboards: <RIGHT>, <LEFT>, <DOWN>, and <UP>; however, many Emacs users find that it is slower to use the arrow keys than the control keys, because you need to move your hand to the area of the keyboard where those keys are located.

You can also click the left mouse button to move point to the position clicked. Emacs also provides a variety of additional keyboard commands that move point in more sophisticated ways.

C-f

Move forward one character (forward-char).

<RIGHT>

This command (right-char) behaves like C-f, except when point is in a right-to-left paragraph (@pxref{Bidirectional Editing}).

C-b

Move backward one character (backward-char).

<LEFT>

This command (left-char) behaves like C-b, except if the current paragraph is right-to-left (@pxref{Bidirectional Editing}).

C-n
<DOWN>

Move down one screen line (next-line). This command attempts to keep the horizontal position unchanged, so if you start in the middle of one line, you move to the middle of the next.

C-p
<UP>

Move up one screen line (previous-line). This command preserves position within the line, like C-n.

C-a
<Home>

Move to the beginning of the line (move-beginning-of-line).

C-e
<End>

Move to the end of the line (move-end-of-line).

M-f

Move forward one word (forward-word). @xref{Words}.

C-<RIGHT>
M-<RIGHT>

This command (right-word) behaves like M-f, except it moves backward by one word if the current paragraph is right-to-left. @xref{Bidirectional Editing}.

M-b

Move backward one word (backward-word). @xref{Words}.

C-<LEFT>
M-<LEFT>

This command (left-word) behaves like M-b, except it moves forward by one word if the current paragraph is right-to-left. @xref{Bidirectional Editing}.

M-r

Without moving the text on the screen, reposition point on the left margin of the center-most text line of the window; on subsequent consecutive invocations, move point to the left margin of the top-most line, the bottom-most line, and so forth, in cyclic order (move-to-window-line-top-bottom).

A numeric argument says which screen line to place point on, counting downward from the top of the window (zero means the top line). A negative argument counts lines up from the bottom (-1 means the bottom line). See section Numeric Arguments, for more information on numeric arguments.

M-<

Move to the top of the buffer (beginning-of-buffer). With numeric argument n, move to n/10 of the way from the top. On graphical displays, C-<HOME> does the same.

M->

Move to the end of the buffer (end-of-buffer). On graphical displays, C-<END> does the same.

C-v
<PageDown>
<next>

Scroll the display one screen forward, and move point onscreen if necessary (scroll-up-command). @xref{Scrolling}.

M-v
<PageUp>
<prior>

Scroll one screen backward, and move point onscreen if necessary (scroll-down-command). @xref{Scrolling}.

M-g c

Read a number n and move point to buffer position n. Position 1 is the beginning of the buffer.

M-g M-g
M-g g

Read a number n and move point to the beginning of line number n (goto-line). Line 1 is the beginning of the buffer. If point is on or just after a number in the buffer, that is the default for n. Just type <RET> in the minibuffer to use it. You can also specify n by giving M-g M-g a numeric prefix argument. @xref{Select Buffer}, for the behavior of M-g M-g when you give it a plain prefix argument.

M-g <TAB>

Read a number n and move to column n in the current line. Column 0 is the leftmost column. If called with a prefix argument, move to the column number specified by the argument’s numeric value.

C-x C-n

Use the current column of point as the semipermanent goal column for C-n and C-p (set-goal-column) in the current buffer. When a semipermanent goal column is in effect, those commands always try to move to this column, or as close as possible to it, after moving vertically. The goal column remains in effect until canceled.

C-u C-x C-n

Cancel the goal column. Henceforth, C-n and C-p try to preserve the horizontal position, as usual.

When a line of text in the buffer is longer than the width of the window, Emacs usually displays it on two or more screen lines. For convenience, C-n and C-p move point by screen lines, as do the equivalent keys <down> and <up>. You can force these commands to move according to logical lines (i.e., according to the text lines in the buffer) by setting the variable line-move-visual to nil; if a logical line occupies multiple screen lines, the cursor then skips over the additional screen lines. For details, see Continuation Lines. @xref{Variables}, for how to set variables such as line-move-visual.

Unlike C-n and C-p, most of the Emacs commands that work on lines work on logical lines. For instance, C-a (move-beginning-of-line) and C-e (move-end-of-line) respectively move to the beginning and end of the logical line. Whenever we encounter commands that work on screen lines, such as C-n and C-p, we will point these out.

When line-move-visual is nil, you can also set the variable track-eol to a non-nil value. Then C-n and C-p, when starting at the end of the logical line, move to the end of the next logical line. Normally, track-eol is nil.

C-n normally stops at the end of the buffer when you use it on the last line in the buffer. However, if you set the variable next-line-add-newlines to a non-nil value, C-n on the last line of a buffer creates an additional line at the end and moves down into it.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Erasing Text

<DEL>
<BACKSPACE>

Delete the character before point, or the region if it is active (delete-backward-char).

<Delete>

Delete the character after point, or the region if it is active (delete-forward-char).

C-d

Delete the character after point (delete-char).

C-k

Kill to the end of the line (kill-line).

M-d

Kill forward to the end of the next word (kill-word).

M-<DEL>
M-<BACKSPACE>

Kill back to the beginning of the previous word (backward-kill-word).

The <DEL> (delete-backward-char) command removes the character before point, moving the cursor and the characters after it backwards. If point was at the beginning of a line, this deletes the preceding newline, joining this line to the previous one.

If, however, the region is active, <DEL> instead deletes the text in the region. @xref{Mark}, for a description of the region.

On most keyboards, <DEL> is labeled <BACKSPACE>, but we refer to it as <DEL> in this manual. (Do not confuse <DEL> with the <Delete> key; we will discuss <Delete> momentarily.) On some text terminals, Emacs may not recognize the <DEL> key properly. @xref{DEL Does Not Delete}, if you encounter this problem.

The <Delete> (delete-forward-char) command deletes in the opposite direction: it deletes the character after point, i.e., the character under the cursor. If point was at the end of a line, this joins the following line onto this one. Like <DEL>, it deletes the text in the region if the region is active (@pxref{Mark}).

C-d (delete-char) deletes the character after point, similar to <Delete>, but regardless of whether the region is active.

@xref{Deletion}, for more detailed information about the above deletion commands.

C-k (kill-line) erases (kills) a line at a time. If you type C-k at the beginning or middle of a line, it kills all the text up to the end of the line. If you type C-k at the end of a line, it joins that line with the following line.

@xref{Killing}, for more information about C-k and related commands.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Undoing Changes

C-/
C-x u
C-_

Undo one entry of the undo records—usually, one command worth (undo). (The first key might be unavailable on text-mode displays.)

Emacs records a list of changes made in the buffer text, so you can undo recent changes. This is done using the undo command, which is bound to C-/ (as well as C-x u and C-_). Normally, this command undoes the last change, moving point back to where it was before the change. The undo command applies only to changes in the buffer; you can’t use it to undo cursor motion.

Although each editing command usually makes a separate entry in the undo records, very simple commands may be grouped together. Sometimes, an entry may cover just part of a complex command.

If you repeat C-/ (or its aliases), each repetition undoes another, earlier change, back to the limit of the undo information available. If all recorded changes have already been undone, the undo command displays an error message and does nothing.

To learn more about the undo command, see @ref{Undo}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Files

Text that you insert in an Emacs buffer lasts only as long as the Emacs session. To keep any text permanently, you must put it in a file.

Suppose there is a file named ‘test.emacs’ in your home directory. To begin editing this file in Emacs, type

C-x C-f test.emacs <RET>

Here the file name is given as an argument to the command C-x C-f (find-file). That command uses the minibuffer to read the argument, and you type <RET> to terminate the argument (@pxref{Minibuffer}).

Emacs obeys this command by visiting the file: it creates a buffer, copies the contents of the file into the buffer, and then displays the buffer for editing. If you alter the text, you can save the new text in the file by typing C-x C-s (save-buffer). This copies the altered buffer contents back into the file ‘test.emacs’, making them permanent. Until you save, the changed text exists only inside Emacs, and the file ‘test.emacs’ is unaltered.

To create a file, just visit it with C-x C-f as if it already existed. This creates an empty buffer, in which you can insert the text you want to put in the file. Emacs actually creates the file the first time you save this buffer with C-x C-s.

To learn more about using files in Emacs, see @ref{Files}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Help

If you forget what a key does, you can find out by typing C-h k (describe-key), followed by the key of interest; for example, C-h k C-n tells you what C-n does.

The prefix key C-h stands for “help”. The key <F1> serves as an alias for C-h. Apart from C-h k, there are many other help commands providing different kinds of help.

@xref{Help}, for details.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Blank Lines

Here are special commands and techniques for inserting and deleting blank lines.

C-o

Insert a blank line after the cursor (open-line).

C-x C-o

Delete all but one of many consecutive blank lines (delete-blank-lines).

We have seen how <RET> (newline) starts a new line of text. However, it may be easier to see what you are doing if you first make a blank line and then insert the desired text into it. This is easy to do using the key C-o (open-line), which inserts a newline after point but leaves point in front of the newline. After C-o, type the text for the new line.

You can make several blank lines by typing C-o several times, or by giving it a numeric argument specifying how many blank lines to make. See section Numeric Arguments, for how. If you have a fill prefix, the C-o command inserts the fill prefix on the new line, if typed at the beginning of a line. @xref{Fill Prefix}.

The easy way to get rid of extra blank lines is with the command C-x C-o (delete-blank-lines). If point lies within a run of several blank lines, C-x C-o deletes all but one of them. If point is on a single blank line, C-x C-o deletes it. If point is on a nonblank line, C-x C-o deletes all following blank lines, if any exists.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Continuation Lines

Sometimes, a line of text in the buffer—a logical line—is too long to fit in the window, and Emacs displays it as two or more screen lines. This is called line wrapping or continuation, and the long logical line is called a continued line. On a graphical display, Emacs indicates line wrapping with small bent arrows in the left and right window fringes. On a text terminal, Emacs indicates line wrapping by displaying a ‘\’ character at the right margin.

Most commands that act on lines act on logical lines, not screen lines. For instance, C-k kills a logical line. As described earlier, C-n (next-line) and C-p (previous-line) are special exceptions: they move point down and up, respectively, by one screen line (see section Changing the Location of Point).

Emacs can optionally truncate long logical lines instead of continuing them. This means that every logical line occupies a single screen line; if it is longer than the width of the window, the rest of the line is not displayed. On a graphical display, a truncated line is indicated by a small straight arrow in the right fringe; on a text terminal, it is indicated by a ‘$’ character in the right margin. @xref{Line Truncation}.

By default, continued lines are wrapped at the right window edge. Since the wrapping may occur in the middle of a word, continued lines can be difficult to read. The usual solution is to break your lines before they get too long, by inserting newlines. If you prefer, you can make Emacs insert a newline automatically when a line gets too long, by using Auto Fill mode. @xref{Filling}.

Sometimes, you may need to edit files containing many long logical lines, and it may not be practical to break them all up by adding newlines. In that case, you can use Visual Line mode, which enables word wrapping: instead of wrapping long lines exactly at the right window edge, Emacs wraps them at the word boundaries (i.e., space or tab characters) nearest to the right window edge. Visual Line mode also redefines editing commands such as C-a, C-n, and C-k to operate on screen lines rather than logical lines. @xref{Visual Line Mode}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 Cursor Position Information

Here are commands to get information about the size and position of parts of the buffer, and to count words and lines.

M-x what-line

Display the line number of point.

M-x line-number-mode
M-x column-number-mode

Toggle automatic display of the current line number or column number. @xref{Optional Mode Line}. If you want to have a line number displayed before each line, see @ref{Display Custom}.

M-=

Display the number of lines, words, and characters that are present in the region (count-words-region). @xref{Mark}, for information about the region.

M-x count-words

Display the number of lines, words, and characters that are present in the buffer. If the region is active (@pxref{Mark}), display the numbers for the region instead.

C-x =

Display the character code of character after point, character position of point, and column of point (what-cursor-position).

M-x hl-line-mode

Enable or disable highlighting of the current line. @xref{Cursor Display}.

M-x size-indication-mode

Toggle automatic display of the size of the buffer. @xref{Optional Mode Line}.

M-x what-line displays the current line number in the echo area. This command is usually redundant because the current line number is shown in the mode line (@pxref{Mode Line}). However, if you narrow the buffer, the mode line shows the line number relative to the accessible portion (@pxref{Narrowing}). By contrast, what-line displays both the line number relative to the narrowed region and the line number relative to the whole buffer.

M-= (count-words-region) displays a message reporting the number of lines, words, and characters in the region (@pxref{Mark}, for an explanation of the region). With a prefix argument, C-u M-=, the command displays a count for the entire buffer.

The command M-x count-words does the same job, but with a different calling convention. It displays a count for the region if the region is active, and for the buffer otherwise.

The command C-x = (what-cursor-position) shows information about the current cursor position and the buffer contents at that position. It displays a line in the echo area that looks like this:

Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53

After ‘Char:’, this shows the character in the buffer at point. The text inside the parenthesis shows the corresponding decimal, octal and hex character codes; for more information about how C-x = displays character information, see @ref{International Chars}. After ‘point=’ is the position of point as a character count (the first character in the buffer is position 1, the second character is position 2, and so on). The number after that is the total number of characters in the buffer, and the number in parenthesis expresses the position as a percentage of the total. After ‘column=’ is the horizontal position of point, in columns counting 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 inaccessible, C-x = displays additional text describing the currently accessible range. For example, it might display this:

Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0

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 accessible ones. @xref{Narrowing}.

Related, but different feature is display-line-numbers-mode (@pxref{Display Custom}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 Numeric Arguments

In the terminology of mathematics and computing, argument means “data provided to a function or operation”. You can give any Emacs command a numeric argument (also called a prefix argument). Some commands interpret the argument as a repetition count. For example, giving C-f an argument of ten causes it to move point forward by ten characters instead of one. With these commands, no argument is equivalent to an argument of one, and negative arguments cause them to move or act in the opposite direction.

The easiest way to specify a numeric argument is to type a digit and/or a minus sign while holding down the <Meta> key. For example,

M-5 C-n

moves down five lines. The keys M-1, M-2, and so on, as well as M--, are bound to commands (digit-argument and negative-argument) that set up an argument for the next command. M-- without digits normally means -1.

If you enter more than one digit, you need not hold down the <Meta> key for the second and subsequent digits. Thus, to move down fifty lines, type

M-5 0 C-n

Note that this does not insert five copies of ‘0’ and move down one line, as you might expect—the ‘0’ is treated as part of the prefix argument.

(What if you do want to insert five copies of ‘0’? Type M-5 C-u 0. Here, C-u terminates the prefix argument, so that the next keystroke begins the command that you want to execute. Note that this meaning of C-u applies only to this case. For the usual role of C-u, see below.)

Instead of typing M-1, M-2, and so on, another way to specify a numeric argument is to type C-u (universal-argument) followed by some digits, or (for a negative argument) a minus sign followed by digits. A minus sign without digits normally means -1.

C-u alone has the special meaning of “four times”: it multiplies the argument for the next command by four. C-u C-u multiplies it by sixteen. Thus, C-u C-u C-f moves forward sixteen characters. 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 sixteen blank lines), and C-u C-k (kill four lines).

You can use a numeric argument before a self-inserting character to insert multiple copies of it. This is straightforward when the character is not a digit; for example, C-u 6 4 a inserts 64 copies of the character ‘a’. But this does not work for inserting digits; C-u 6 4 1 specifies an argument of 641. You can separate the argument from the digit to insert with another C-u; for example, C-u 6 4 C-u 1 does insert 64 copies of the character ‘1’.

Some commands care whether there is an argument, but ignore its value. For example, the command M-q (fill-paragraph) fills text; with an argument, it justifies the text as well. (@xref{Filling}, for more information on M-q.) For these commands, it is enough to specify the argument with a single C-u.

Some commands use the value of the argument as a repeat count but do something special 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 nonblank line, just like C-k with an argument of one. (@xref{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 are described when they come up; they exist to make an individual command more convenient, and they are documented in that command’s documentation string.

We use the term prefix argument to emphasize that you type such arguments before the command, and to distinguish them from minibuffer arguments (@pxref{Minibuffer}), which are entered after invoking the command.

On graphical displays, C-0, C-1, etc. act the same as M-0, M-1, etc.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.11 Repeating a Command

Many simple commands, such as those invoked with a single key or with M-x command-name <RET>, can be repeated by invoking them with a numeric argument that serves as a repeat count (see section Numeric Arguments). However, if the command you want to repeat prompts for input, or uses a numeric argument in another way, that method won’t work.

The command C-x z (repeat) provides another way to repeat an Emacs command many times. This command repeats the previous Emacs command, whatever that was. Repeating a command uses the same arguments that were used before; it does not read new arguments each time.

To repeat the command more than once, type additional z’s: each z repeats the command one more time. Repetition ends when you type a character other than z or press a mouse button.

For example, suppose you type C-u 2 0 C-d to delete 20 characters. You can repeat that command (including its argument) three additional times, to delete a total of 80 characters, by typing C-x z z z. The first C-x z repeats the command once, and each subsequent z repeats it once again.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 30, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on May 30, 2018 using texi2html.