# HG changeset patch # User Glenn Morris # Date 1189053501 0 # Node ID 429dd288d5871d659097e11d2808154a273a9458 # Parent 4fa4881ed489613d34f43485216758a29649b866 Move to ../doc/emacs/, misc/ diff -r 4fa4881ed489 -r 429dd288d587 man/mark.texi --- a/man/mark.texi Thu Sep 06 04:38:16 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,452 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 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 -@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}). - - 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 -effect on other buffers' marks. When you return to a buffer that was -current earlier, its mark is at the same place as before. - - 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. - - Many commands that insert text, such as @kbd{C-y} (@code{yank}) and -@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. - - 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. -* Momentary Mark:: Enabling Transient Mark mode momentarily. -* 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 where you clicked (like -@kbd{Mouse-1}). - - Using the mouse to mark a region copies the region into the kill -ring in addition to setting the mark; that gives behavior consistent -with other window-driven applications. 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 -the new position with point back at its original position. - - 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 -@cindex highlighting region -@cindex region highlighting - - On a terminal that supports colors, Emacs has the ability to -highlight the current region. But normally it does not. Why not? - - In the normal mode of use, every command that sets the mark also -activates it, and nothing ever deactivates it. Thus, once you have -set the mark in a buffer, there is @emph{always} a region in that -buffer. Highlighting the region all the time would be a nuisance. So -normally Emacs highlights the region only immediately after you have -selected one with the mouse. - - If you want region highlighting, you can use Transient Mark mode. -This is a more rigid mode of operation in which the region ``lasts'' -only until you use it; operating on the region text deactivates the -mark, so there is no region any more. Therefore, you must explicitly -set up a region for each command that uses one. - - When Transient Mark mode is enabled, Emacs highlights the region, -whenever there is a region. In Transient Mark mode, most of the time -there is no region; therefore, highlighting the region when it exists -is useful and not annoying. - -@findex transient-mark-mode - To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}. -This command toggles the mode; you can use the same command to turn -the mode off again. - - Here are the details of Transient Mark mode: - -@itemize @bullet -@item -To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}). -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. - -@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 -You can tell that the mark is active because the region is highlighted. - -@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 -If Delete Selection mode is also enabled, some commands delete the -region when used while the mark is active. @xref{Mouse Commands}. - -@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 -@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. -@end itemize - - 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}. - -@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 -is enabled and the mark in the window's buffer is active). - -@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, so you can still use -region commands. - -@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 Momentary Mark -@section Using Transient Mark Mode Momentarily - - If you don't like Transient Mark mode in general, you might still -want to use it once in a while. To do this, type @kbd{C-@key{SPC} -C-@key{SPC}} or @kbd{C-u C-x C-x}. These commands set or activate the -mark, and enable Transient Mark mode only until the mark is -deactivated. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -@kindex C-@key{SPC} C-@key{SPC} -Set the mark at point (like plain @kbd{C-@key{SPC}}), and enable -Transient Mark mode just once until the mark is deactivated. (This is -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 - 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{Printing}). -@item -Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). -@item -Undo changes within it using @kbd{C-u C-x u} (@pxref{Undo}). -@end itemize - - Most commands that operate on the text in the region have the word -@code{region} in their names. - -@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-@@ -Set mark after end of next word (@code{mark-word}). This command and -the following one do not move point. -@item C-M-@@ -Set mark after end of following balanced expression (@code{mark-sexp}). -@item M-h -Put region around current paragraph (@code{mark-paragraph}). -@item C-M-h -Put region around current defun (@code{mark-defun}). -@item C-x h -Put region around the entire buffer (@code{mark-whole-buffer}). -@item C-x C-p -Put region around current page (@code{mark-page}). -@end table - -@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}. Repeating these -commands extends the region. For example, you can type either -@kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words. These -commands also extend the region 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 -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 a 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 to subsequent paragraphs. - - @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} extends -the region to subsequent 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 (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. (In some programs this is called ``select all.'') - - 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 -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}). - -@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 -another one is pushed, the earliest one in the list is discarded. Repeating -@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. - -@ignore - arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20 -@end ignore