mark.texi 15.9 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1
@c This is part of the Emacs manual.
Eli Zaretskii's avatar
Eli Zaretskii committed
2
@c Copyright (C) 1985,86,87,93,94,95,1997,2001 Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16
@c See file emacs.texi for copying conditions.
@node Mark, Killing, Help, Top
@chapter The Mark and the Region
@cindex mark
@cindex setting a mark
@cindex 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 @dfn{the mark} at one end of it, and move point to the other
end.  The text between point and the mark is called @dfn{the region}.
Emacs highlights the region whenever there is one, if you enable
Transient Mark mode (@pxref{Transient Mark}).

17 18 19
  Certain Emacs commands set the mark; other editing commands do not
affect it, so the mark remains where you set it last.  Each Emacs
buffer has its own mark, and setting the mark in one buffer has no
Richard M. Stallman's avatar
Richard M. Stallman committed
20 21
effect on other buffers' marks.  When you return to a buffer that was
current earlier, its mark is at the same place as before.
22 23 24 25 26 27 28

  The ends of the region are always point and the mark.  It doesn't
matter which of them was put in its current place first, or which one
comes earlier in the text---the region starts from point or the mark
(whichever comes first), and ends at point or the mark (whichever
comes last).  Every time you move point, or set the mark in a new
place, the region changes.
Dave Love's avatar
#  
Dave Love committed
29 30

  Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
31 32 33
@kbd{M-x insert-buffer}, position point and the mark at opposite ends
of the inserted text, so that the region consists of the text just
inserted.
Dave Love's avatar
#  
Dave Love committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96

  Aside from delimiting the region, the mark is also useful for
remembering a spot that you may want to go back to.  To make this
feature more useful, each buffer remembers 16 previous locations of the
mark in the @dfn{mark ring}.

@menu
* Setting Mark::	Commands to set the mark.
* Transient Mark::	How to make Emacs highlight the region--
			  when there is one.
* Using Region::	Summary of ways to operate on contents of the region.
* Marking Objects::	Commands to put region around textual units.
* Mark Ring::   	Previous mark positions saved so you can go back there.
* Global Mark Ring::    Previous mark positions in various buffers.
@end menu

@node Setting Mark
@section Setting the Mark

  Here are some commands for setting the mark:

@table @kbd
@item C-@key{SPC}
Set the mark where point is (@code{set-mark-command}).
@item C-@@
The same.
@item C-x C-x
Interchange mark and point (@code{exchange-point-and-mark}).
@item Drag-Mouse-1
Set point and the mark around the text you drag across.
@item Mouse-3
Set the mark where point is, then move point to where you click
(@code{mouse-save-then-kill}).
@end table

  For example, suppose you wish to convert part of the buffer to
upper case, using the @kbd{C-x C-u} (@code{upcase-region}) command,
which operates on the text in the region.  You can first go to the
beginning of the text to be capitalized, type @kbd{C-@key{SPC}} to put
the mark there, move to the end, and then type @kbd{C-x C-u}.  Or, you
can set the mark at the end of the text, move to the beginning, and then
type @kbd{C-x C-u}.

@kindex C-SPC
@findex set-mark-command
  The most common way to set the mark is with the @kbd{C-@key{SPC}} command
(@code{set-mark-command}).  This sets the mark where point is.  Then you
can move point away, leaving the mark behind.

  There are two ways to set the mark with the mouse.  You can drag mouse
button one across a range of text; that puts point where you release the
mouse button, and sets the mark at the other end of that range.  Or you
can click mouse button three, which sets the mark at point (like
@kbd{C-@key{SPC}}) and then moves point (like @kbd{Mouse-1}).  Both of
these methods copy the region into the kill ring in addition to setting
the mark; that gives behavior consistent with other window-driven
applications, but if you don't want to modify the kill ring, you must
use keyboard commands to set the mark.  @xref{Mouse Commands}.

@kindex C-x C-x
@findex exchange-point-and-mark
  Ordinary terminals have only one cursor, so there is no way for Emacs
to show you where the mark is located.  You have to remember.  The usual
97
solution to this problem is to set the mark and then use it soon, before
Dave Love's avatar
#  
Dave Love committed
98 99 100 101 102 103 104 105 106 107
you forget where it is.  Alternatively, you can see where the mark is
with the command @kbd{C-x C-x} (@code{exchange-point-and-mark}) which
puts the mark where point was and point where the mark was.  The extent
of the region is unchanged, but the cursor and point are now at the
previous position of the mark.  In Transient Mark mode, this command
reactivates the mark.

  @kbd{C-x C-x} is also useful when you are satisfied with the position
of point but want to move the other end of the region (where the mark
is); do @kbd{C-x C-x} to put point at that end of the region, and then
108
move it.  Using @kbd{C-x C-x} a second time, if necessary, puts the mark at
Dave Love's avatar
#  
Dave Love committed
109 110
the new position with point back at its original position.

111 112 113
  For more facilities that allow you to go to previously set marks, see
@ref{Mark Ring}.

Dave Love's avatar
#  
Dave Love committed
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
@kindex C-@@
  There is no such character as @kbd{C-@key{SPC}} in ASCII; when you
type @key{SPC} while holding down @key{CTRL}, what you get on most
ordinary terminals is the character @kbd{C-@@}.  This key is actually
bound to @code{set-mark-command}.  But unless you are unlucky enough to
have a terminal where typing @kbd{C-@key{SPC}} does not produce
@kbd{C-@@}, you might as well think of this character as
@kbd{C-@key{SPC}}.  Under X, @kbd{C-@key{SPC}} is actually a distinct
character, but its binding is still @code{set-mark-command}.

@node Transient Mark
@section Transient Mark Mode
@cindex mode, Transient Mark
@cindex Transient Mark mode
@cindex highlighting region
@cindex region highlighting

131 132
  On a terminal that supports colors, Emacs can highlight the current
region.  But normally it does not.  Why not?
Dave Love's avatar
#  
Dave Love committed
133

134 135 136 137
  Highlighting the region whenever it exists would not be desirable in
Emacs, because once you have set a mark, there is @emph{always} a
region (in that buffer).  And highlighting the region all the time
would be a nuisance.  So normally Emacs highlights the region only
Richard M. Stallman's avatar
Richard M. Stallman committed
138
immediately after you have selected one with the mouse.
Dave Love's avatar
#  
Dave Love committed
139 140 141 142 143

  You can turn on region highlighting by enabling Transient Mark mode.
This is a more rigid mode of operation in which the region ``lasts''
only temporarily, so you must set up a region for each command that uses
one.  In Transient Mark mode, most of the time there is no region;
144 145
therefore, highlighting the region when it exists is useful and
not annoying.
Dave Love's avatar
#  
Dave Love committed
146 147 148 149 150 151 152 153 154 155 156

@findex transient-mark-mode
  To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}.
This command toggles the mode, so you can repeat the command to turn off
the mode.

  Here are the details of Transient Mark mode:

@itemize @bullet
@item
To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}).
Richard M. Stallman's avatar
Richard M. Stallman committed
157 158 159
This makes the mark active and thus begins highlighting of the region.
As you move point, you will see the highlighted region grow and
shrink.
Dave Love's avatar
#  
Dave Love committed
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177

@item 
The mouse commands for specifying the mark also make it active.  So do
keyboard commands whose purpose is to specify a region, including
@kbd{M-@@}, @kbd{C-M-@@}, @kbd{M-h}, @kbd{C-M-h}, @kbd{C-x C-p}, and
@kbd{C-x h}.

@item
When the mark is active, you can execute commands that operate on the
region, such as killing, indenting, or writing to a file.

@item
Any change to the buffer, such as inserting or deleting a character,
deactivates the mark.  This means any subsequent command that operates
on a region will get an error and refuse to operate.  You can make the
region active again by typing @kbd{C-x C-x}.

@item
Richard M. Stallman's avatar
Richard M. Stallman committed
178
Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in
179
addition to some other primary purpose, do not activate the new mark.
Dave Love's avatar
#  
Dave Love committed
180 181 182 183 184 185 186 187
You can activate the new region by executing @kbd{C-x C-x}
(@code{exchange-point-and-mark}).

@item
@kbd{C-s} when the mark is active does not alter the mark.

@item
Quitting with @kbd{C-g} deactivates the mark.
188 189 190 191 192 193 194 195

@item
Some commands operate on the region whenever it is active.  For
instance, @kbd{C-x u} in Transient Mark mode operates on the region
when there is a region.  Outside Transient Mark mode, you must type
@kbd{C-u C-x u} if you want it to operate on the region.
@xref{Undo}.   Other commands that act this way are identified
in their own documentation.
Dave Love's avatar
#  
Dave Love committed
196 197
@end itemize

198 199 200
  The highlighting of the region uses the @code{region} face; you can
customize the appearance of the highlighted region by changing this
face.  @xref{Face Customization}.
Dave Love's avatar
#  
Dave Love committed
201 202 203 204 205 206 207 208

@vindex highlight-nonselected-windows
  When multiple windows show the same buffer, they can have different
regions, because they can have different values of point (though they
all share one common mark position).  Ordinarily, only the selected
window highlights its region (@pxref{Windows}).  However, if the
variable @code{highlight-nonselected-windows} is non-@code{nil}, then
each window highlights its own region (provided that Transient Mark mode
Richard M. Stallman's avatar
Richard M. Stallman committed
209
is enabled and the mark in the window's buffer is active).
Dave Love's avatar
#  
Dave Love committed
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

  When Transient Mark mode is not enabled, every command that sets the
mark also activates it, and nothing ever deactivates it.

@vindex mark-even-if-inactive
  If the variable @code{mark-even-if-inactive} is non-@code{nil} in
Transient Mark mode, then commands can use the mark and the region
even when it is inactive.  Region highlighting appears and disappears 
just as it normally does in Transient Mark mode, but the mark doesn't
really go away when the highlighting disappears.

@cindex Zmacs mode
  Transient Mark mode is also sometimes known as ``Zmacs mode''
because the Zmacs editor on the MIT Lisp Machine handled the mark in a
similar way.

@node Using Region
@section Operating on the Region

@cindex operations on a marked region
  Once you have a region and the mark is active, here are some of the
ways you can operate on the region:

@itemize @bullet
@item
Kill it with @kbd{C-w} (@pxref{Killing}).
@item
Save it in a register with @kbd{C-x r s} (@pxref{Registers}).
@item
Save it in a buffer or a file (@pxref{Accumulating Text}).
@item
Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}).
@item
Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
@item
Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}).
@item
Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
@item
Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
@end itemize

252
  Most commands that operate on the text in the region have the word
253
@code{region} in their names.
Dave Love's avatar
#  
Dave Love committed
254 255 256 257 258 259 260 261 262 263

@node Marking Objects
@section Commands to Mark Textual Objects

@cindex marking sections of text
  Here are the commands for placing point and the mark around a textual
object such as a word, list, paragraph or page.

@table @kbd
@item M-@@
Richard M. Stallman's avatar
Richard M. Stallman committed
264
Set mark after end of next word (@code{mark-word}).  This command and
Dave Love's avatar
#  
Dave Love committed
265 266
the following one do not move point.
@item C-M-@@
Richard M. Stallman's avatar
Richard M. Stallman committed
267
Set mark after end of following balanced expression (@code{mark-sexp}).
Dave Love's avatar
#  
Dave Love committed
268
@item M-h
Richard M. Stallman's avatar
Richard M. Stallman committed
269
Put region around current paragraph (@code{mark-paragraph}).
Dave Love's avatar
#  
Dave Love committed
270
@item C-M-h
Richard M. Stallman's avatar
Richard M. Stallman committed
271
Put region around current defun (@code{mark-defun}).
Dave Love's avatar
#  
Dave Love committed
272
@item C-x h
273
Put region around the entire buffer (@code{mark-whole-buffer}).
Dave Love's avatar
#  
Dave Love committed
274
@item C-x C-p
Richard M. Stallman's avatar
Richard M. Stallman committed
275
Put region around current page (@code{mark-page}).
Dave Love's avatar
#  
Dave Love committed
276 277
@end table

278 279 280 281
@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next
word, while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the
next balanced expression (@pxref{Expressions}).  These commands handle
arguments just like @kbd{M-f} and @kbd{C-M-f}.
Dave Love's avatar
#  
Dave Love committed
282 283 284 285 286

@kindex C-x h
@findex mark-whole-buffer
   Other commands set both point and mark, to delimit an object in the
buffer.  For example, @kbd{M-h} (@code{mark-paragraph}) moves point to
287 288 289 290 291 292 293 294 295 296
the beginning of the paragraph that surrounds or follows point, and
puts the mark at the end of that paragraph (@pxref{Paragraphs}).  It
prepares the region so you can indent, case-convert, or kill a whole
paragraph.  With prefix argument, if the argument's value is positive,
@kbd{M-h} marks that many paragraphs, the paragraph surrounding point
plus some following paragraphs.  If the prefix argument is negative,
@kbd{M-h} also marks that many paragraphs, but the preceding ones
instead of the following.  (With a positive argument, point is put
at the beginning and mark at end, with a negative argument, point is
at end and mark at the beginning.)
Dave Love's avatar
#  
Dave Love committed
297

298
  @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the
Richard M. Stallman's avatar
Richard M. Stallman committed
299
mark after, the current (or following) major top-level definition, or
Richard M. Stallman's avatar
Richard M. Stallman committed
300 301 302
defun (@pxref{Moving by Defuns}).  @kbd{C-x C-p} (@code{mark-page})
puts point before the current page, and mark at the end
(@pxref{Pages}).  The mark goes after the terminating page delimiter
Richard M. Stallman's avatar
Richard M. Stallman committed
303 304 305 306
(to include it in the region), while point goes after the preceding
page delimiter (to exclude it).  A numeric argument specifies a later
page (if positive) or an earlier page (if negative) instead of the
current page.
Dave Love's avatar
#  
Dave Love committed
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324

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

  In Transient Mark mode, all of these commands activate the mark.

@node Mark Ring
@section The Mark Ring

@kindex C-u C-SPC
@cindex mark ring
@kindex C-u C-@@
  Aside from delimiting the region, the mark is also useful for
remembering a spot that you may want to go back to.  To make this
feature more useful, each buffer remembers 16 previous locations of the
mark, in the @dfn{mark ring}.  Commands that set the mark also push the
old mark onto this ring.  To return to a marked location, use @kbd{C-u
Eli Zaretskii's avatar
Eli Zaretskii committed
325
C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command
Dave Love's avatar
#  
Dave Love committed
326 327 328 329 330 331 332 333 334 335 336 337 338 339
@code{set-mark-command} given a numeric argument.  It moves point to
where the mark was, and restores the mark from the ring of former
marks.  Thus, repeated use of this command moves point to all of the old
marks on the ring, one by one.  The mark positions you move through in
this way are not lost; they go to the end of the ring.

  Each buffer has its own mark ring.  All editing commands use the current
buffer's mark ring.  In particular, @kbd{C-u C-@key{SPC}} always stays in
the same buffer.

  Many commands that can move long distances, such as @kbd{M-<}
(@code{beginning-of-buffer}), start by setting the mark and saving the
old mark on the mark ring.  This is to make it easier for you to move
back later.  Searches set the mark if they move point.  You can tell
340
when a command sets the mark because it displays @samp{Mark set} in the
Dave Love's avatar
#  
Dave Love committed
341 342 343 344
echo area.

  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
345 346
in a register for later retrieval (@pxref{RegPos,, Saving Positions in
Registers}).
Dave Love's avatar
#  
Dave Love committed
347 348 349 350

@vindex mark-ring-max
  The variable @code{mark-ring-max} specifies the maximum number of
entries to keep in the mark ring.  If that many entries exist and
351
another one is pushed, the earliest one in the list is discarded.  Repeating
Dave Love's avatar
#  
Dave Love committed
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381
@kbd{C-u C-@key{SPC}} cycles through the positions currently in the
ring.

@vindex mark-ring
  The variable @code{mark-ring} holds the mark ring itself, as a list of
marker objects, with the most recent first.  This variable is local in
every buffer.

@node Global Mark Ring
@section The Global Mark Ring
@cindex global mark ring

  In addition to the ordinary mark ring that belongs to each buffer,
Emacs has a single @dfn{global mark ring}.  It records a sequence of
buffers in which you have recently set the mark, so you can go back
to those buffers.

  Setting the mark always makes an entry on the current buffer's mark
ring.  If you have switched buffers since the previous mark setting, the
new mark position makes an entry on the global mark ring also.  The
result is that 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.

@kindex C-x C-@key{SPC}
@findex pop-global-mark
  The command @kbd{C-x C-@key{SPC}} (@code{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 @kbd{C-x C-@key{SPC}} take
you to earlier and earlier buffers.