Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
b65d8176 TTN |
2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, |
3 | @c 2003, 2004, 2005 Free Software Foundation, Inc. | |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Mark, Killing, Help, Top | |
6 | @chapter The Mark and the Region | |
7 | @cindex mark | |
8 | @cindex setting a mark | |
9 | @cindex region | |
10 | ||
11 | Many Emacs commands operate on an arbitrary contiguous part of the | |
12 | current buffer. To specify the text for such a command to operate on, | |
13 | you set @dfn{the mark} at one end of it, and move point to the other | |
14 | end. The text between point and the mark is called @dfn{the region}. | |
15 | Emacs highlights the region whenever there is one, if you enable | |
16 | Transient Mark mode (@pxref{Transient Mark}). | |
17 | ||
401aa479 RS |
18 | Certain Emacs commands set the mark; other editing commands do not |
19 | affect it, so the mark remains where you set it last. Each Emacs | |
20 | buffer has its own mark, and setting the mark in one buffer has no | |
a9749dab RS |
21 | effect on other buffers' marks. When you return to a buffer that was |
22 | current earlier, its mark is at the same place as before. | |
401aa479 RS |
23 | |
24 | The ends of the region are always point and the mark. It doesn't | |
25 | matter which of them was put in its current place first, or which one | |
26 | comes earlier in the text---the region starts from point or the mark | |
27 | (whichever comes first), and ends at point or the mark (whichever | |
28 | comes last). Every time you move point, or set the mark in a new | |
29 | place, the region changes. | |
6bf7aab6 DL |
30 | |
31 | Many commands that insert text, such as @kbd{C-y} (@code{yank}) and | |
401aa479 RS |
32 | @kbd{M-x insert-buffer}, position point and the mark at opposite ends |
33 | of the inserted text, so that the region consists of the text just | |
34 | inserted. | |
6bf7aab6 DL |
35 | |
36 | Aside from delimiting the region, the mark is also useful for | |
37 | remembering a spot that you may want to go back to. To make this | |
38 | feature more useful, each buffer remembers 16 previous locations of the | |
39 | mark in the @dfn{mark ring}. | |
40 | ||
41 | @menu | |
42 | * Setting Mark:: Commands to set the mark. | |
43 | * Transient Mark:: How to make Emacs highlight the region-- | |
44 | when there is one. | |
37281adb | 45 | * Momentary Mark:: Enabling Transient Mark mode momentarily. |
6bf7aab6 DL |
46 | * Using Region:: Summary of ways to operate on contents of the region. |
47 | * Marking Objects:: Commands to put region around textual units. | |
48 | * Mark Ring:: Previous mark positions saved so you can go back there. | |
49 | * Global Mark Ring:: Previous mark positions in various buffers. | |
50 | @end menu | |
51 | ||
52 | @node Setting Mark | |
53 | @section Setting the Mark | |
54 | ||
55 | Here are some commands for setting the mark: | |
56 | ||
6bf7aab6 DL |
57 | @table @kbd |
58 | @item C-@key{SPC} | |
59 | Set the mark where point is (@code{set-mark-command}). | |
60 | @item C-@@ | |
61 | The same. | |
62 | @item C-x C-x | |
63 | Interchange mark and point (@code{exchange-point-and-mark}). | |
64 | @item Drag-Mouse-1 | |
65 | Set point and the mark around the text you drag across. | |
66 | @item Mouse-3 | |
67 | Set the mark where point is, then move point to where you click | |
68 | (@code{mouse-save-then-kill}). | |
69 | @end table | |
70 | ||
71 | For example, suppose you wish to convert part of the buffer to | |
72 | upper case, using the @kbd{C-x C-u} (@code{upcase-region}) command, | |
73 | which operates on the text in the region. You can first go to the | |
74 | beginning of the text to be capitalized, type @kbd{C-@key{SPC}} to put | |
75 | the mark there, move to the end, and then type @kbd{C-x C-u}. Or, you | |
76 | can set the mark at the end of the text, move to the beginning, and then | |
77 | type @kbd{C-x C-u}. | |
78 | ||
79 | @kindex C-SPC | |
80 | @findex set-mark-command | |
81 | The most common way to set the mark is with the @kbd{C-@key{SPC}} command | |
82 | (@code{set-mark-command}). This sets the mark where point is. Then you | |
83 | can move point away, leaving the mark behind. | |
84 | ||
85 | There are two ways to set the mark with the mouse. You can drag mouse | |
86 | button one across a range of text; that puts point where you release the | |
87 | mouse button, and sets the mark at the other end of that range. Or you | |
88 | can click mouse button three, which sets the mark at point (like | |
87c190c7 RS |
89 | @kbd{C-@key{SPC}}) and then moves point where you clicked (like |
90 | @kbd{Mouse-1}). Both of these methods copy the region into the kill | |
91 | ring in addition to setting the mark; that gives behavior consistent | |
92 | with other window-driven applications, but if you don't want to modify | |
93 | the kill ring, you must use keyboard commands to set the mark. | |
94 | @xref{Mouse Commands}. | |
6bf7aab6 DL |
95 | |
96 | @kindex C-x C-x | |
97 | @findex exchange-point-and-mark | |
87c190c7 RS |
98 | When Emacs was developed, terminals had only one cursor, so Emacs |
99 | does not show where the mark is located--you have to remember. If you | |
100 | enable Transient Mark mode (see below), then the region is highlighted | |
101 | when it is active; you can tell mark is at the other end of the | |
102 | highlighted region. But this only applies when the mark is active. | |
103 | ||
104 | The usual solution to this problem is to set the mark and then use | |
105 | it soon, before you forget where it is. Alternatively, you can see | |
106 | where the mark is with the command @kbd{C-x C-x} | |
107 | (@code{exchange-point-and-mark}) which puts the mark where point was | |
108 | and point where the mark was. The extent of the region is unchanged, | |
109 | but the cursor and point are now at the previous position of the mark. | |
110 | In Transient Mark mode, this command also reactivates the mark. | |
6bf7aab6 DL |
111 | |
112 | @kbd{C-x C-x} is also useful when you are satisfied with the position | |
113 | of point but want to move the other end of the region (where the mark | |
114 | is); do @kbd{C-x C-x} to put point at that end of the region, and then | |
58fa012d | 115 | move it. Using @kbd{C-x C-x} a second time, if necessary, puts the mark at |
6bf7aab6 DL |
116 | the new position with point back at its original position. |
117 | ||
3508c523 EZ |
118 | For more facilities that allow you to go to previously set marks, see |
119 | @ref{Mark Ring}. | |
120 | ||
6bf7aab6 | 121 | @kindex C-@@ |
87c190c7 RS |
122 | There is no such character as @kbd{C-@key{SPC}} in @acronym{ASCII}; |
123 | when you type @key{SPC} while holding down @key{CTRL} on a text | |
124 | terminal, what you get is the character @kbd{C-@@}. This key is also | |
125 | bound to @code{set-mark-command}--so unless you are unlucky enough to | |
126 | have a text terminal where typing @kbd{C-@key{SPC}} does not produce | |
6bf7aab6 | 127 | @kbd{C-@@}, you might as well think of this character as |
87c190c7 | 128 | @kbd{C-@key{SPC}}. |
6bf7aab6 DL |
129 | |
130 | @node Transient Mark | |
131 | @section Transient Mark Mode | |
132 | @cindex mode, Transient Mark | |
133 | @cindex Transient Mark mode | |
134 | @cindex highlighting region | |
135 | @cindex region highlighting | |
136 | ||
37281adb RS |
137 | On a terminal that supports colors, Emacs has the ability to |
138 | highlight the current region. But normally it does not. Why not? | |
139 | ||
140 | Once you have set the mark in a buffer, there is @emph{always} a | |
141 | region in that buffer. This is because every command that sets the | |
142 | mark also activates it, and nothing ever deactivates it. Highlighting | |
143 | the region all the time would be a nuisance. So normally Emacs | |
144 | highlights the region only immediately after you have selected one | |
145 | with the mouse. | |
146 | ||
147 | If you want region highlighting, you can use Transient Mark mode. | |
148 | This is a more rigid mode of operation in which the region always | |
149 | ``lasts'' only until you use it; you explicitly must set up a region | |
150 | for each command that uses one. In Transient Mark mode, most of the | |
151 | time there is no region; therefore, highlighting the region when it | |
152 | exists is useful and not annoying. When Transient Mark mode is | |
153 | enabled, Emacs always highlights the region whenever there is a | |
154 | region. | |
6bf7aab6 DL |
155 | |
156 | @findex transient-mark-mode | |
157 | To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}. | |
37281adb RS |
158 | This command toggles the mode; you can use the same command to turn |
159 | the mode off again. | |
6bf7aab6 DL |
160 | |
161 | Here are the details of Transient Mark mode: | |
162 | ||
163 | @itemize @bullet | |
164 | @item | |
165 | To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}). | |
a9749dab RS |
166 | This makes the mark active and thus begins highlighting of the region. |
167 | As you move point, you will see the highlighted region grow and | |
168 | shrink. | |
6bf7aab6 | 169 | |
177c0ea7 | 170 | @item |
6bf7aab6 DL |
171 | The mouse commands for specifying the mark also make it active. So do |
172 | keyboard commands whose purpose is to specify a region, including | |
173 | @kbd{M-@@}, @kbd{C-M-@@}, @kbd{M-h}, @kbd{C-M-h}, @kbd{C-x C-p}, and | |
174 | @kbd{C-x h}. | |
175 | ||
37281adb RS |
176 | @item |
177 | You can tell that the mark is active because the region is highlighted. | |
178 | ||
6bf7aab6 DL |
179 | @item |
180 | When the mark is active, you can execute commands that operate on the | |
181 | region, such as killing, indenting, or writing to a file. | |
182 | ||
183 | @item | |
184 | Any change to the buffer, such as inserting or deleting a character, | |
185 | deactivates the mark. This means any subsequent command that operates | |
186 | on a region will get an error and refuse to operate. You can make the | |
187 | region active again by typing @kbd{C-x C-x}. | |
188 | ||
87c190c7 RS |
189 | @item |
190 | If Delete Selection mode is also enabled, some commands delete the | |
191 | region when used while the mark is active. @xref{Graphical Kill}. | |
192 | ||
37281adb RS |
193 | @item |
194 | Quitting with @kbd{C-g} deactivates the mark. | |
195 | ||
6bf7aab6 | 196 | @item |
a9749dab | 197 | Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in |
58fa012d | 198 | addition to some other primary purpose, do not activate the new mark. |
6bf7aab6 DL |
199 | You can activate the new region by executing @kbd{C-x C-x} |
200 | (@code{exchange-point-and-mark}). | |
201 | ||
202 | @item | |
93e8fd61 JL |
203 | Commands that normally set the mark before moving long distances (like |
204 | @kbd{M-<} and @kbd{C-s}) do not alter the mark in Transient Mark mode | |
205 | when the mark is active. | |
6bf7aab6 DL |
206 | |
207 | @item | |
37281adb RS |
208 | Some commands operate on the region if a region is active. For |
209 | instance, @kbd{C-x u} in Transient Mark mode operates on the region, | |
210 | when there is a region. (Outside Transient Mark mode, you must type | |
211 | @kbd{C-u C-x u} if you want it to operate on the region.) | |
212 | @xref{Undo}. Other commands that act this way are identified in their | |
213 | own documentation. | |
6bf7aab6 DL |
214 | @end itemize |
215 | ||
58fa012d EZ |
216 | The highlighting of the region uses the @code{region} face; you can |
217 | customize the appearance of the highlighted region by changing this | |
218 | face. @xref{Face Customization}. | |
6bf7aab6 DL |
219 | |
220 | @vindex highlight-nonselected-windows | |
221 | When multiple windows show the same buffer, they can have different | |
222 | regions, because they can have different values of point (though they | |
223 | all share one common mark position). Ordinarily, only the selected | |
224 | window highlights its region (@pxref{Windows}). However, if the | |
225 | variable @code{highlight-nonselected-windows} is non-@code{nil}, then | |
226 | each window highlights its own region (provided that Transient Mark mode | |
a9749dab | 227 | is enabled and the mark in the window's buffer is active). |
6bf7aab6 | 228 | |
6bf7aab6 DL |
229 | @vindex mark-even-if-inactive |
230 | If the variable @code{mark-even-if-inactive} is non-@code{nil} in | |
231 | Transient Mark mode, then commands can use the mark and the region | |
37281adb | 232 | even when it is inactive. Region highlighting appears and disappears |
6bf7aab6 | 233 | just as it normally does in Transient Mark mode, but the mark doesn't |
37281adb RS |
234 | really go away when the highlighting disappears, so you can still use |
235 | region commands. | |
6bf7aab6 DL |
236 | |
237 | @cindex Zmacs mode | |
238 | Transient Mark mode is also sometimes known as ``Zmacs mode'' | |
239 | because the Zmacs editor on the MIT Lisp Machine handled the mark in a | |
240 | similar way. | |
241 | ||
37281adb RS |
242 | @node Momentary Mark |
243 | @section Using Transient Mark Mode Momentarily | |
244 | ||
245 | If you don't like Transient Mark mode in general, you might still | |
246 | want to use it once in a while. To do this, type @kbd{C-@key{SPC} | |
247 | C-@key{SPC}} or @kbd{C-u C-x C-x}. These commands set or activate the | |
248 | mark, and enable Transient Mark mode only until the mark is | |
249 | deactivated. | |
250 | ||
251 | @table @kbd | |
252 | @item C-@key{SPC} C-@key{SPC} | |
253 | @kindex C-@key{SPC} C-@key{SPC} | |
254 | Set the mark at point (like plain @kbd{C-@key{SPC}}), and enable | |
255 | Transient Mark mode just once until the mark is deactivated. (This is | |
256 | not really a separate command; you are using the @kbd{C-@key{SPC}} | |
257 | command twice.) | |
258 | ||
259 | @item C-u C-x C-x | |
260 | @kindex C-u C-x C-x | |
a401596d RS |
261 | Activate the mark without changing it; enable Transient Mark mode just |
262 | once, until the mark is deactivated. (This is the @kbd{C-x C-x} | |
263 | command, @code{exchange-point-and-mark}, with a prefix argument.) | |
37281adb RS |
264 | @end table |
265 | ||
266 | One of the secondary features of Transient Mark mode is that certain | |
a401596d RS |
267 | commands operate only on the region, when there is an active region. |
268 | If you don't use Transient Mark mode, the region once set never | |
269 | becomes inactive, so there is no way for these commands to make such a | |
37281adb RS |
270 | distinction. Enabling Transient Mark mode momentarily gives you a way |
271 | to use these commands on the region. | |
272 | ||
a401596d RS |
273 | Momentary use of Transient Mark mode is also a way to highlight the |
274 | region for the time being. | |
37281adb | 275 | |
6bf7aab6 DL |
276 | @node Using Region |
277 | @section Operating on the Region | |
278 | ||
279 | @cindex operations on a marked region | |
280 | Once you have a region and the mark is active, here are some of the | |
281 | ways you can operate on the region: | |
282 | ||
283 | @itemize @bullet | |
284 | @item | |
285 | Kill it with @kbd{C-w} (@pxref{Killing}). | |
286 | @item | |
287 | Save it in a register with @kbd{C-x r s} (@pxref{Registers}). | |
288 | @item | |
289 | Save it in a buffer or a file (@pxref{Accumulating Text}). | |
290 | @item | |
291 | Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). | |
292 | @item | |
293 | Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). | |
294 | @item | |
295 | Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). | |
296 | @item | |
cb4a6fe1 | 297 | Print hardcopy with @kbd{M-x print-region} (@pxref{Printing}). |
6bf7aab6 DL |
298 | @item |
299 | Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). | |
300 | @end itemize | |
301 | ||
7da970c0 | 302 | Most commands that operate on the text in the region have the word |
58fa012d | 303 | @code{region} in their names. |
6bf7aab6 DL |
304 | |
305 | @node Marking Objects | |
306 | @section Commands to Mark Textual Objects | |
307 | ||
308 | @cindex marking sections of text | |
309 | Here are the commands for placing point and the mark around a textual | |
310 | object such as a word, list, paragraph or page. | |
311 | ||
312 | @table @kbd | |
313 | @item M-@@ | |
a9749dab | 314 | Set mark after end of next word (@code{mark-word}). This command and |
6bf7aab6 DL |
315 | the following one do not move point. |
316 | @item C-M-@@ | |
a9749dab | 317 | Set mark after end of following balanced expression (@code{mark-sexp}). |
6bf7aab6 | 318 | @item M-h |
a9749dab | 319 | Put region around current paragraph (@code{mark-paragraph}). |
6bf7aab6 | 320 | @item C-M-h |
a9749dab | 321 | Put region around current defun (@code{mark-defun}). |
6bf7aab6 | 322 | @item C-x h |
58fa012d | 323 | Put region around the entire buffer (@code{mark-whole-buffer}). |
6bf7aab6 | 324 | @item C-x C-p |
a9749dab | 325 | Put region around current page (@code{mark-page}). |
6bf7aab6 DL |
326 | @end table |
327 | ||
366c721e RS |
328 | @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next |
329 | word, while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the | |
330 | next balanced expression (@pxref{Expressions}). These commands handle | |
cad113ae | 331 | arguments just like @kbd{M-f} and @kbd{C-M-f}. If you repeat these |
87c190c7 RS |
332 | commands, that extends the region. For example, you can type either |
333 | @kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words. This | |
334 | command also extends the region when the mark is active in Transient | |
335 | Mark mode, regardless of the last command. | |
6bf7aab6 DL |
336 | |
337 | @kindex C-x h | |
338 | @findex mark-whole-buffer | |
339 | Other commands set both point and mark, to delimit an object in the | |
340 | buffer. For example, @kbd{M-h} (@code{mark-paragraph}) moves point to | |
564b1f76 EZ |
341 | the beginning of the paragraph that surrounds or follows point, and |
342 | puts the mark at the end of that paragraph (@pxref{Paragraphs}). It | |
343 | prepares the region so you can indent, case-convert, or kill a whole | |
344 | paragraph. With prefix argument, if the argument's value is positive, | |
e7c210cc RS |
345 | @kbd{M-h} marks that many paragraphs starting with the one surrounding |
346 | point. If the prefix argument is @minus{}@var{n}, @kbd{M-h} also | |
347 | marks @var{n} paragraphs, running back form the one surrounding point. | |
348 | In that last case, point moves forward to the end of that paragraph, | |
87c190c7 RS |
349 | and the mark goes at the start of the region. Repeating the @kbd{M-h} |
350 | command extends the region, just as with @kbd{M-@@} and @kbd{C-M-@@}. | |
6bf7aab6 | 351 | |
58fa012d | 352 | @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the |
a9749dab | 353 | mark after, the current (or following) major top-level definition, or |
87c190c7 RS |
354 | defun (@pxref{Moving by Defuns}). Repeating @kbd{C-M-h} also extends |
355 | the region. | |
356 | ||
357 | @kbd{C-x C-p} (@code{mark-page}) puts point before the current page, | |
358 | and mark at the end (@pxref{Pages}). The mark goes after the | |
359 | terminating page delimiter (to include it in the region), while point | |
360 | goes after the preceding page delimiter (to exclude it). A numeric | |
361 | argument specifies a later page (if positive) or an earlier page (if | |
362 | negative) instead of the current page. | |
6bf7aab6 DL |
363 | |
364 | Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire | |
365 | buffer as the region, by putting point at the beginning and the mark at | |
366 | the end. | |
367 | ||
368 | In Transient Mark mode, all of these commands activate the mark. | |
369 | ||
370 | @node Mark Ring | |
371 | @section The Mark Ring | |
372 | ||
373 | @kindex C-u C-SPC | |
374 | @cindex mark ring | |
375 | @kindex C-u C-@@ | |
376 | Aside from delimiting the region, the mark is also useful for | |
377 | remembering a spot that you may want to go back to. To make this | |
378 | feature more useful, each buffer remembers 16 previous locations of the | |
379 | mark, in the @dfn{mark ring}. Commands that set the mark also push the | |
380 | old mark onto this ring. To return to a marked location, use @kbd{C-u | |
4125ceb0 | 381 | C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command |
6bf7aab6 DL |
382 | @code{set-mark-command} given a numeric argument. It moves point to |
383 | where the mark was, and restores the mark from the ring of former | |
37281adb RS |
384 | marks. |
385 | ||
386 | If you repeat the character @kbd{C-@key{SPC}}, after typing @kbd{C-u | |
387 | C-@key{SPC}}, each repetition moves point to a previous mark position | |
388 | from the ring. The mark positions you move through in this way are | |
389 | not lost; they go to the end of the ring. | |
6bf7aab6 DL |
390 | |
391 | Each buffer has its own mark ring. All editing commands use the current | |
392 | buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in | |
393 | the same buffer. | |
394 | ||
395 | Many commands that can move long distances, such as @kbd{M-<} | |
396 | (@code{beginning-of-buffer}), start by setting the mark and saving the | |
397 | old mark on the mark ring. This is to make it easier for you to move | |
93e8fd61 JL |
398 | back later. Searches set the mark if they move point. However, in |
399 | Transient Mark mode, these commands do not set the mark when the mark | |
400 | is already active. You can tell when a command sets the mark because | |
401 | it displays @samp{Mark set} in the echo area. | |
6bf7aab6 DL |
402 | |
403 | If you want to move back to the same place over and over, the mark | |
404 | ring may not be convenient enough. If so, you can record the position | |
96a48d43 RS |
405 | in a register for later retrieval (@pxref{RegPos,, Saving Positions in |
406 | Registers}). | |
6bf7aab6 DL |
407 | |
408 | @vindex mark-ring-max | |
409 | The variable @code{mark-ring-max} specifies the maximum number of | |
410 | entries to keep in the mark ring. If that many entries exist and | |
58fa012d | 411 | another one is pushed, the earliest one in the list is discarded. Repeating |
6bf7aab6 DL |
412 | @kbd{C-u C-@key{SPC}} cycles through the positions currently in the |
413 | ring. | |
414 | ||
415 | @vindex mark-ring | |
416 | The variable @code{mark-ring} holds the mark ring itself, as a list of | |
417 | marker objects, with the most recent first. This variable is local in | |
418 | every buffer. | |
419 | ||
420 | @node Global Mark Ring | |
421 | @section The Global Mark Ring | |
422 | @cindex global mark ring | |
423 | ||
424 | In addition to the ordinary mark ring that belongs to each buffer, | |
425 | Emacs has a single @dfn{global mark ring}. It records a sequence of | |
426 | buffers in which you have recently set the mark, so you can go back | |
427 | to those buffers. | |
428 | ||
429 | Setting the mark always makes an entry on the current buffer's mark | |
430 | ring. If you have switched buffers since the previous mark setting, the | |
431 | new mark position makes an entry on the global mark ring also. The | |
432 | result is that the global mark ring records a sequence of buffers that | |
433 | you have been in, and, for each buffer, a place where you set the mark. | |
434 | ||
435 | @kindex C-x C-@key{SPC} | |
436 | @findex pop-global-mark | |
437 | The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to | |
438 | the buffer and position of the latest entry in the global ring. It also | |
439 | rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take | |
440 | you to earlier and earlier buffers. | |
441 | ||
ab5796a9 MB |
442 | @ignore |
443 | arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20 | |
444 | @end ignore |