diff man/mark.texi @ 25829:ac7e9e5e2ccb

#

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/mark.texi	Wed Sep 29 15:17:24 1999 +0000
@@ -0,0 +1,351 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 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}).
+
+  You can move point or the mark to adjust the boundaries of the region.
+It doesn't matter which one is set first chronologically, or which one
+comes earlier in the text.  Once the mark has been set, it remains where
+you put it until you set it again at another place.  Each Emacs buffer
+has its own mark, so that when you return to a buffer that had been
+selected previously, it has the same mark it had before.
+
+  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 contains 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.
+* 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:
+
+@c WideCommands
+@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
+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
+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.  A second use of @kbd{C-x C-x}, if necessary, puts the mark at
+the new position with point back at its original position.
+
+@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
+
+  Emacs can highlight the current region, using X Windows.  But normally
+it does not.  Why not?
+
+  Highlighting the region doesn't work well ordinarily 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.
+
+  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;
+therefore, highlighting the region when it exists is convenient.
+
+@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}).
+This makes the mark active; as you move point, you will see the region
+highlighting 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
+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
+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
+Quitting with @kbd{C-g} deactivates the mark.
+@end itemize
+
+  Highlighting of the region uses the @code{region} face; you can
+customize how the region is highlighted 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 window's buffer's mark is active).
+
+  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
+
+  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 next Lisp expression (@code{mark-sexp}).
+@item M-h
+Put region around current paragraph (@code{mark-paragraph}).
+@item C-M-h
+Put region around current Lisp defun (@code{mark-defun}).
+@item C-x h
+Put region around 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 Lisp
+expression.  These commands handle arguments just like @kbd{M-f} and
+@kbd{C-M-f}.
+
+@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.
+
+  @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the
+mark after the current or following defun (@pxref{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), 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 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.  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
+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}).
+
+@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 last 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.
+