"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/emacs/mark.texi" (14 Apr 2017, 20845 Bytes) of package /linux/misc/emacs-25.3.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 last Fossies "Diffs" side-by-side code changes report for "mark.texi": 25.1_vs_25.2.

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

1 The Mark and the Region

Many Emacs commands operate on an arbitrary contiguous part of the current buffer. To specify the text for such a command to operate on, you set the mark at one end of it, and move point to the other end. The text between point and the mark is called the region. The region always extends between point and the mark, no matter which one comes earlier in the text; each time you move point, the region changes.

Setting the mark at a position in the text also activates it. When the mark is active, we say also that the region is active; Emacs indicates its extent by highlighting the text within it, using the region face (@pxref{Face Customization}).

After certain non-motion commands, including any command that changes the text in the buffer, Emacs automatically deactivates the mark; this turns off the highlighting. You can also explicitly deactivate the mark at any time, by typing C-g (@pxref{Quitting}).

The above default behavior is known as Transient Mark mode. Disabling Transient Mark mode switches Emacs to an alternative behavior, in which the region is usually not highlighted. See section Disabling Transient Mark Mode.

Setting the mark in one buffer has no effect on the marks in other buffers. When you return to a buffer with an active mark, the mark is at the same place as before. When multiple windows show the same buffer, they can have different values of point, and thus different regions, but they all share one common mark position. @xref{Windows}. Ordinarily, only the selected window highlights its region; however, if the variable highlight-nonselected-windows is non-nil, each window highlights its own region.

There is another kind of region: the rectangular region. @xref{Rectangles}.


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

1.1 Setting the Mark

Here are some commands for setting the mark:

C-<SPC>

Set the mark at point, and activate it (set-mark-command).

C-@

The same.

C-x C-x

Set the mark at point, and activate it; then move point where the mark used to be (exchange-point-and-mark).

Drag-mouse-1

Set point and the mark around the text you drag across.

mouse-3

Set the mark at point, then move point to where you click (mouse-save-then-kill).

Shifted cursor motion keys

Set the mark at point if the mark is inactive, then move point. See section Shift Selection.

The most common way to set the mark is with C-<SPC> (set-mark-command)(1). This sets the mark where point is, and activates it. You can then move point away, leaving the mark behind.

For example, suppose you wish to convert part of the buffer to upper case. To accomplish this, go to one end of the desired text, type C-<SPC>, and move point until the desired portion of text is highlighted. Now type C-x C-u (upcase-region). This converts the text in the region to upper case, and then deactivates the mark.

Whenever the mark is active, you can deactivate it by typing C-g (@pxref{Quitting}). Most commands that operate on the region also automatically deactivate the mark, like C-x C-u in the above example.

Instead of setting the mark in order to operate on a region, you can also use it to remember a position in the buffer (by typing C-<SPC> C-<SPC>), and later jump back there (by typing C-u C-<SPC>). See section The Mark Ring, for details.

The command C-x C-x (exchange-point-and-mark) exchanges the positions of point and the mark. C-x C-x is useful when you are satisfied with the position of point but want to move the other end of the region (where the mark is). Using C-x C-x a second time, if necessary, puts the mark at the new position with point back at its original position. Normally, if the mark is inactive, this command first reactivates the mark wherever it was last set, to ensure that the region is left highlighted. However, if you call it with a prefix argument, it leaves the mark inactive and the region unhighlighted; you can use this to jump to the mark in a manner similar to C-u C-<SPC>.

You can also set the mark with the mouse. If you press the left mouse button (down-mouse-1) and drag the mouse across a range of text, this sets the mark where you first pressed the mouse button and puts point where you release it. Alternatively, clicking the right mouse button (mouse-3) sets the mark at point and then moves point to where you clicked. @xref{Mouse Commands}, for a more detailed description of these mouse commands.

Finally, you can set the mark by holding down the shift key while typing certain cursor motion commands (such as S-<RIGHT>, S-C-f, S-C-n, etc.). This is called shift-selection. It sets the mark at point before moving point, but only if there is no active mark set via shift-selection. The mark set by mouse commands and by shift-selection behaves slightly differently from the usual mark: any subsequent unshifted cursor motion command deactivates it automatically. For details, See section Shift Selection.

Many commands that insert text, such as C-y (yank), set the mark at the other end of the inserted text, without activating it. This lets you easily return to that position (see section The Mark Ring). You can tell that a command does this when it shows ‘Mark set’ in the echo area.

Under X, every time the active region changes, Emacs saves the text in the region to the primary selection. This lets you insert that text into other X applications with mouse-2 clicks. @xref{Primary Selection}.


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

1.2 Commands to Mark Textual Objects

Here are commands for placing point and the mark around a textual object such as a word, list, paragraph or page:

M-@

Set mark after end of next word (mark-word). This does not move point.

C-M-@

Set mark after end of following balanced expression (mark-sexp). This does not move point.

M-h

Move point to the beginning of the current paragraph, and set mark at the end (mark-paragraph).

C-M-h

Move point to the beginning of the current defun, and set mark at the end (mark-defun).

C-x C-p

Move point to the beginning of the current page, and set mark at the end (mark-page).

C-x h

Move point to the beginning of the buffer, and set mark at the end (mark-whole-buffer).

M-@ (mark-word) sets the mark at the end of the next word (@pxref{Words}, for information about words). Repeated invocations of this command extend the region by advancing the mark one word at a time. As an exception, if the mark is active and located before point, M-@ moves the mark backwards from its current position one word at a time.

This command also accepts a numeric argument n, which tells it to advance the mark by n words. A negative argument moves the mark back by n words.

Similarly, C-M-@ (mark-sexp) puts the mark at the end of the next balanced expression (@pxref{Expressions}). Repeated invocations extend the region to subsequent expressions, while positive or negative numeric arguments move the mark forward or backward by the specified number of expressions.

The other commands in the above list set both point and mark, so as to delimit an object in the buffer. M-h (mark-paragraph) marks paragraphs (@pxref{Paragraphs}), C-M-h (mark-defun) marks top-level definitions (@pxref{Moving by Defuns}), and C-x C-p (mark-page) marks pages (@pxref{Pages}). Repeated invocations again play the same role, extending the region to consecutive objects; similarly, numeric arguments specify how many objects to move the mark by.

C-x h (mark-whole-buffer) sets up the entire buffer as the region, by putting point at the beginning and the mark at the end.


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

1.3 Operating on the Region

Once you have a region, here are some of the ways you can operate on it:

Some commands have a default behavior when the mark is inactive, but operate on the region if the mark is active. For example, M-$ (ispell-word) normally checks the spelling of the word at point, but it checks the text in the region if the mark is active (@pxref{Spelling}). Normally, such commands use their default behavior if the region is empty (i.e., if mark and point are at the same position). If you want them to operate on the empty region, change the variable use-empty-active-region to t.

As described in @ref{Erasing}, the <DEL> (backward-delete-char) and <delete> (delete-forward-char) commands also act this way. If the mark is active, they delete the text in the region. (As an exception, if you supply a numeric argument n, where n is not one, these commands delete n characters regardless of whether the mark is active). If you change the variable delete-active-region to nil, then these commands don’t act differently when the mark is active. If you change the value to kill, these commands kill the region instead of deleting it (@pxref{Killing}).

Other commands always operate on the region, and have no default behavior. Such commands usually have the word region in their names, like C-w (kill-region) and C-x C-u (upcase-region). If the mark is inactive, they operate on the inactive region—that is, on the text between point and the position at which the mark was last set (see section The Mark Ring). To disable this behavior, change the variable mark-even-if-inactive to nil. Then these commands will instead signal an error if the mark is inactive.

By default, text insertion occurs normally even if the mark is active—for example, typing a inserts the character ‘a’, then deactivates the mark. Delete Selection mode, a minor mode, modifies this behavior: if you enable that mode, then inserting text while the mark is active causes the text in the region to be deleted first. Also, commands that normally delete just one character, such as C-d or <DEL>, will delete the entire region instead. To toggle Delete Selection mode on or off, type M-x delete-selection-mode.


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

1.4 The Mark Ring

Each buffer remembers previous locations of the mark, in the mark ring. Commands that set the mark also push the old mark onto this ring. One of the uses of the mark ring is to remember spots that you may want to go back to.

C-<SPC> C-<SPC>

Set the mark, pushing it onto the mark ring, without activating it.

C-u C-<SPC>

Move point to where the mark was, and restore the mark from the ring of former marks.

The command C-<SPC> C-<SPC> is handy when you want to use the mark to remember a position to which you may wish to return. It pushes the current point onto the mark ring, without activating the mark (which would cause Emacs to highlight the region). This is actually two consecutive invocations of C-<SPC> (set-mark-command); the first C-<SPC> sets the mark, and the second C-<SPC> deactivates it. (When Transient Mark mode is off, C-<SPC> C-<SPC> instead activates Transient Mark mode temporarily; see section Disabling Transient Mark Mode.)

To return to a marked position, use set-mark-command with a prefix argument: C-u C-<SPC>. This moves point to where the mark was, and deactivates the mark if it was active. Each subsequent C-u C-<SPC> jumps to a prior position stored in the mark ring. The positions you move through in this way are not lost; they go to the end of the ring.

If you set set-mark-command-repeat-pop to non-nil, then immediately after you type C-u C-<SPC>, you can type C-<SPC> instead of C-u C-<SPC> to cycle through the mark ring. By default, set-mark-command-repeat-pop is nil.

Each buffer has its own mark ring. All editing commands use the current buffer’s mark ring. In particular, C-u C-<SPC> always stays in the same buffer.

The variable mark-ring-max specifies the maximum number of entries to keep in the mark ring. This defaults to 16 entries. If that many entries exist and another one is pushed, the earliest one in the list is discarded. Repeating C-u C-<SPC> cycles through the positions currently in the ring.

If you want to move back to the same place over and over, the mark ring may not be convenient enough. If so, you can record the position in a register for later retrieval (@pxref{Position Registers,, Saving Positions in Registers}).


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

1.5 The Global Mark Ring

In addition to the ordinary mark ring that belongs to each buffer, Emacs has a single global mark ring. Each time you set a mark, this is recorded in the global mark ring in addition to the current buffer’s own mark ring, if you have switched buffers since the previous mark setting. Hence, the global mark ring records a sequence of buffers that you have been in, and, for each buffer, a place where you set the mark. The length of the global mark ring is controlled by global-mark-ring-max, and is 16 by default.

The command C-x C-<SPC> (pop-global-mark) jumps to the buffer and position of the latest entry in the global ring. It also rotates the ring, so that successive uses of C-x C-<SPC> take you to earlier buffers and mark positions.


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

1.6 Shift Selection

If you hold down the shift key while typing a cursor motion command, this sets the mark before moving point, so that the region extends from the original position of point to its new position. This feature is referred to as shift-selection. It is similar to the way text is selected in other editors.

The mark set via shift-selection behaves a little differently from what we have described above. Firstly, in addition to the usual ways of deactivating the mark (such as changing the buffer text or typing C-g), the mark is deactivated by any unshifted cursor motion command. Secondly, any subsequent shifted cursor motion command avoids setting the mark anew. Therefore, a series of shifted cursor motion commands will continuously adjust the region.

Shift-selection only works if the shifted cursor motion key is not already bound to a separate command (@pxref{Customization}). For example, if you bind S-C-f to another command, typing S-C-f runs that command instead of performing a shift-selected version of C-f (forward-char).

A mark set via mouse commands behaves the same as a mark set via shift-selection (see section Setting the Mark). For example, if you specify a region by dragging the mouse, you can continue to extend the region using shifted cursor motion commands. In either case, any unshifted cursor motion command deactivates the mark.

To turn off shift-selection, set shift-select-mode to nil. Doing so does not disable setting the mark via mouse commands.


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

1.7 Disabling Transient Mark Mode

The default behavior of the mark and region, in which setting the mark activates it and highlights the region, is called Transient Mark mode. This is a minor mode that is enabled by default. It can be toggled with M-x transient-mark-mode, or with the ‘Active Region Highlighting’ menu item in the ‘Options’ menu. Turning it off switches Emacs to an alternative mode of operation:

While Transient Mark mode is off, you can activate it temporarily using C-<SPC> C-<SPC> or C-u C-x C-x.

C-<SPC> C-<SPC>

Set the mark at point (like plain C-<SPC>) and enable Transient Mark mode just once, until the mark is deactivated. (This is not really a separate command; you are using the C-<SPC> command twice.)

C-u C-x C-x

Exchange point and mark, activate the mark and enable Transient Mark mode temporarily, until the mark is next deactivated. (This is the C-x C-x command, exchange-point-and-mark, with a prefix argument.)

These commands set or activate the mark, and enable Transient Mark mode only until the mark is deactivated. One reason you may want to use them is that some commands operate on the entire buffer instead of the region when Transient Mark mode is off. Enabling Transient Mark mode momentarily gives you a way to use these commands on the region.

When you specify a region with the mouse (see section Setting the Mark), or with shift-selection (see section Shift Selection), this likewise activates Transient Mark mode temporarily and highlights the region.


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

Footnotes

(1)

There is no C-<SPC> character in ASCII; usually, typing C-<SPC> on a text terminal gives the character C-@. This key is also bound to set-mark-command, so unless you are unlucky enough to have a text terminal that behaves differently, you might as well think of C-@ as C-<SPC>.


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

About This Document

This document was generated on September 23, 2017 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 September 23, 2017 using texi2html.