comparison man/mark.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

@c This is part of the Emacs manual.
@c Copyright (C) 1985,86,87,93,94,95,1997,2001 Free Software Foundation, Inc.
@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

  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
solution to this problem is to set the mark and then use it soon, before
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
also 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
move it.  Using @kbd{C-x C-x} a second time, if necessary, puts the mark at

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

@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

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
Quitting with @kbd{C-g} deactivates the mark.

@item
Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in
addition to some other primary purpose, do not activate the new mark.
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
Some commands operate on the region if a region 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

not really a separate command; you are using the @kbd{C-@key{SPC}}
command twice.)

@item C-u C-x C-x
@kindex C-u C-x C-x
Activate the mark without changing it, enable Transient Mark mode just
once until the mark is deactivated.  (This is the @kbd{C-x C-x} command,
@code{exchange-point-and-mark}, with a prefix argument.)
@end table

  One of the secondary features of Transient Mark mode is that certain
commands operate on the region when there is an active region.  If you
don't use Transient Mark mode, the region once set never becomes
inactive, so there is no way these commands to make such a
distinction.  Enabling Transient Mark mode momentarily gives you a way
to use these commands on the region.

  The other way momentarily use of Transient Mark mode is useful
is that it highlights the region for the time being.

@node Using Region
@section Operating on the Region

@cindex operations on a marked region

@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

  Most commands that operate on the text in the region have the word

@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}.  If you repeat these
commands, the region is extended.  For example, you can type either
@kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words.

@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

paragraph.  With prefix argument, if the argument's value is positive,
@kbd{M-h} marks that many paragraphs starting with the one surrounding
point.  If the prefix argument is @minus{}@var{n}, @kbd{M-h} also
marks @var{n} paragraphs, running back form the one surrounding point.
In that last case, point moves forward to the end of that paragraph,
and the mark goes at the start of the region.  The @kbd{M-h} command
also supports the extension of the region, similar to @kbd{M-@@} and
@kbd{C-M-@@}.

  @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the
mark after, the current (or following) major top-level definition, or
defun (@pxref{Moving by Defuns}).  (Currently it only marks one defun,
but repeating it marks more defuns, like for @kbd{M-@@}.)  @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 (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.

  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.

C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command
@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.

  If you repeat the character @kbd{C-@key{SPC}}, after typing @kbd{C-u
C-@key{SPC}}, each repetition moves point to a previous mark position
from the ring.  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
when a command sets the mark because it displays @samp{Mark set} in the
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
in a register for later retrieval (@pxref{RegPos,, Saving Positions in
Registers}).

  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.

88155:d7ddb3e565de

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
@c   2003, 2004, 2005 Free Software Foundation, Inc.
@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

  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 where you clicked (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
  When Emacs was developed, terminals had only one cursor, so Emacs
does not show where the mark is located--you have to remember.  If you
enable Transient Mark mode (see below), then the region is highlighted
when it is active; you can tell mark is at the other end of the
highlighted region.  But this only applies when the mark is active.

  The usual solution to this problem is to set the mark and then use
it soon, before 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 also 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
move it.  Using @kbd{C-x C-x} a second time, if necessary, puts the mark at

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

@kindex C-@@
  There is no such character as @kbd{C-@key{SPC}} in @acronym{ASCII};
when you type @key{SPC} while holding down @key{CTRL} on a text
terminal, what you get is the character @kbd{C-@@}.  This key is also
bound to @code{set-mark-command}--so unless you are unlucky enough to
have a text 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}}.

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

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
If Delete Selection mode is also enabled, some commands delete the
region when used while the mark is active.  @xref{Graphical Kill}.

@item
Quitting with @kbd{C-g} deactivates the mark.

@item
Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in
addition to some other primary purpose, do not activate the new mark.
You can activate the new region by executing @kbd{C-x C-x}
(@code{exchange-point-and-mark}).

@item
Commands that normally set the mark before moving long distances (like
@kbd{M-<} and @kbd{C-s}) do not alter the mark in Transient Mark mode
when the mark is active.

@item
Some commands operate on the region if a region 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

not really a separate command; you are using the @kbd{C-@key{SPC}}
command twice.)

@item C-u C-x C-x
@kindex C-u C-x C-x
Activate the mark without changing it; enable Transient Mark mode just
once, until the mark is deactivated.  (This is the @kbd{C-x C-x}
command, @code{exchange-point-and-mark}, with a prefix argument.)
@end table

  One of the secondary features of Transient Mark mode is that certain
commands operate only on the region, when there is an active region.
If you don't use Transient Mark mode, the region once set never
becomes inactive, so there is no way for these commands to make such a
distinction.  Enabling Transient Mark mode momentarily gives you a way
to use these commands on the region.

  Momentary use of Transient Mark mode is also a way to highlight the
region for the time being.

@node Using Region
@section Operating on the Region

@cindex operations on a marked region

@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{Printing}).
@item
Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
@end itemize

  Most commands that operate on the text in the region have the word

@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}.  If you repeat these
commands, that extends the region.  For example, you can type either
@kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words.  This
command also extends the region when the mark is active in Transient
Mark mode, regardless of the last command.

@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

paragraph.  With prefix argument, if the argument's value is positive,
@kbd{M-h} marks that many paragraphs starting with the one surrounding
point.  If the prefix argument is @minus{}@var{n}, @kbd{M-h} also
marks @var{n} paragraphs, running back form the one surrounding point.
In that last case, point moves forward to the end of that paragraph,
and the mark goes at the start of the region.  Repeating the @kbd{M-h}
command extends the region, just as with @kbd{M-@@} and @kbd{C-M-@@}.

  @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the
mark after, the current (or following) major top-level definition, or
defun (@pxref{Moving by Defuns}).  Repeating @kbd{C-M-h} also extends
the region.

  @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 (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.

  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.

C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command
@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.

@vindex set-mark-command-repeat-pop
  If you set @code{set-mark-command-repeat-pop} to non-@code{nil},
then when you repeat the character @kbd{C-@key{SPC}} after typing
@kbd{C-u C-@key{SPC}}, each repetition moves point to a previous mark
position from the ring.  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.  However, in
Transient Mark mode, these commands do not set the mark when the mark
is already active.  You can tell when a command sets the mark because
it displays @samp{Mark set} in the 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
in a register for later retrieval (@pxref{RegPos,, Saving Positions in
Registers}).

  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.

@ignore
   arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20
@end ignore