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