[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs/doc/lispref ChangeLog markers.texi
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] emacs/doc/lispref ChangeLog markers.texi |
Date: |
Mon, 06 Apr 2009 01:20:56 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Chong Yidong <cyd> 09/04/06 01:20:56
Modified files:
doc/lispref : ChangeLog markers.texi
Log message:
* markers.texi (The Mark): Copyedits. Improve description of
handle-shift-selection.
(The Region): Move use-region-p here from The Mark.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/ChangeLog?cvsroot=emacs&r1=1.251&r2=1.252
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/markers.texi?cvsroot=emacs&r1=1.10&r2=1.11
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.251
retrieving revision 1.252
diff -u -b -r1.251 -r1.252
--- ChangeLog 5 Apr 2009 05:11:48 -0000 1.251
+++ ChangeLog 6 Apr 2009 01:20:55 -0000 1.252
@@ -1,5 +1,9 @@
2009-04-05 Chong Yidong <address@hidden>
+ * markers.texi (The Mark): Copyedits. Improve description of
+ handle-shift-selection.
+ (The Region): Move use-region-p here from The Mark.
+
* positions.texi (Screen Lines): Document (cols . lines) argument
for vertical-motion.
Index: markers.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/markers.texi,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- markers.texi 27 Mar 2009 14:42:36 -0000 1.10
+++ markers.texi 6 Apr 2009 01:20:56 -0000 1.11
@@ -392,44 +392,42 @@
@cindex mark, the
@cindex mark ring
- One special marker in each buffer is designated @dfn{the mark}. It
-specifies a position to bound a range of text for commands such as
address@hidden and @code{indent-rigidly}. Lisp programs should
-set the mark only to values that have a potential use to the user, and
-never for their own internal purposes. For example, the
address@hidden command sets the mark to the value of point
-before doing any replacements, because this enables the user to move
-back there conveniently after the replace is finished.
-
- Many commands are designed to operate on the text between point and
-the mark when called interactively. If you are writing such a
-command, don't examine the mark directly; instead, use
+ Each buffer has a special marker, which is designated @dfn{the
+mark}. When a buffer is newly created, this marker exists but does
+not point anywhere; this means that the mark ``doesn't exist'' in that
+buffer yet. Subsequent commands can set the mark.
+
+ The mark specifies a position to bound a range of text for many
+commands, such as @code{kill-region} and @code{indent-rigidly}. These
+commands typically act on the text between point and the mark, which
+is called the @dfn{region}. If you are writing a command that
+operates on the region, don't examine the mark directly; instead, use
@code{interactive} with the @samp{r} specification. This provides the
values of point and the mark as arguments to the command in an
interactive call, but permits other Lisp programs to specify arguments
explicitly. @xref{Interactive Codes}.
- Each buffer has a marker which represents the value of the mark in
-that buffer, independent of any other buffer. When a buffer is newly
-created, this marker exists but does not point anywhere. That means
-the mark ``doesn't exist'' in that buffer as yet.
+ Some commands set the mark as a side-effect. Commands should do
+this only if it has a potential use to the user, and never for their
+own internal purposes. For example, the @code{replace-regexp} command
+sets the mark to the value of point before doing any replacements,
+because this enables the user to move back there conveniently after
+the replace is finished.
Once the mark ``exists'' in a buffer, it normally never ceases to
-exist. However, it may become @dfn{inactive}, if Transient Mark mode is
-enabled. The variable @code{mark-active}, which is always buffer-local
-in all buffers, indicates whether the mark is active: address@hidden
-means yes. A command can request deactivation of the mark upon return
-to the editor command loop by setting @code{deactivate-mark} to a
address@hidden value (but this causes deactivation only if Transient
-Mark mode is enabled).
+exist. However, it may become @dfn{inactive}, if Transient Mark mode
+is enabled. The buffer-local variable @code{mark-active}, if
address@hidden, means that the mark is active. A command can call the
+function @code{deactivate-mark} to deactivate the mark directly, or it
+can request deactivation of the mark upon return to the editor command
+loop by setting the variable @code{deactivate-mark} to a
address@hidden value.
- Certain editing commands that normally apply to text near point,
-work on the region when Transient Mode is enabled and the mark is
+ If Transient Mode is enabled, certain editing commands that normally
+apply to text near point, apply instead to the region when the mark is
active. This is the main motivation for using Transient Mark mode.
-
- Another motivation for using Transient Mark mode is that this mode
-also enables highlighting of the region when the mark is active.
address@hidden
+(Another is that this enables highlighting of the region when the mark
+is active. @xref{Display}.)
In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers containing previous values of the mark. When editing
@@ -450,8 +448,8 @@
If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
@code{nil}, @code{mark} signals an error if the mark is inactive.
However, if @var{force} is address@hidden, then @code{mark} disregards
-inactivity of the mark, and returns the mark position anyway (or
address@hidden).
+inactivity of the mark, and returns the mark position (or @code{nil})
+anyway.
@end defun
@defun mark-marker
@@ -481,20 +479,6 @@
results. We recommend that you not do it!
@end defun
address@hidden
address@hidden Command set-mark-command jump
-If @var{jump} is @code{nil}, this command sets the mark to the value
-of point and pushes the previous value of the mark on the mark ring. The
-message @samp{Mark set} is also displayed in the echo area.
-
-If @var{jump} is not @code{nil}, this command sets point to the value
-of the mark, and sets the mark to the previous saved mark value, which
-is popped off the mark ring.
-
-This function is @emph{only} intended for interactive use.
address@hidden deffn
address@hidden ignore
-
@defun set-mark position
This function sets the mark to @var{position}, and activates the mark.
The old value of the mark is @emph{not} pushed onto the mark ring.
@@ -522,14 +506,6 @@
@end example
@end defun
address@hidden for interactive use only
address@hidden
address@hidden Command exchange-point-and-mark
-This function exchanges the positions of point and the mark.
-It is intended for interactive use.
address@hidden deffn
address@hidden ignore
-
@defun push-mark &optional position nomsg activate
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}. If
@@ -553,16 +529,15 @@
@end defun
@defopt transient-mark-mode
address@hidden @cindex Transient Mark mode Redundant
-This variable if address@hidden enables Transient Mark mode, in which
-every buffer-modifying primitive sets @code{deactivate-mark}. The
-consequence of this is that commands that modify the buffer normally
-make the mark inactive.
-
-Certain commands normally apply to text near point, but in Transient
-Mark mode when the mark is active, they apply to the region instead.
-These commands should call @code{use-region-p} to test whether they
-should operate on the region.
+This variable, if address@hidden, enables Transient Mark mode. In
+Transient Mark mode, every buffer-modifying primitive sets
address@hidden As a consequence, most commands that modify
+the buffer also deactivate the mark.
+
+When Transient Mark mode is enabled and the mark is active, many
+commands that normally apply to the text near point instead apply to
+the region. Such commands should use the function @code{use-region-p}
+to test whether they should operate on the region. @xref{The Region}.
Lisp programs can set @code{transient-mark-mode} to address@hidden,
address@hidden values to enable Transient Mark mode temporarily. If the
@@ -575,14 +550,6 @@
action that would normally deactivate the mark.
@end defopt
address@hidden use-region-p
-This function returns @code{t} if Transient Mark mode is enabled, the
-mark is active, and there's a valid region in the buffer. Commands
-that operate on the region (instead of on text near point) when
-there's an active mark should use this subroutine to test whether to
-do that.
address@hidden defun
-
@defopt mark-even-if-inactive
If this is address@hidden, Lisp programs and the Emacs user can use the
mark even when it is inactive. This option affects the behavior of
@@ -619,7 +586,7 @@
variable is always buffer-local in each buffer. Do @emph{not} use the
value of this variable to decide whether a command that normally
operates on text near point should operate on the region instead. Use
-the @code{use-region-p} subroutine (see above) for that.
+the function @code{use-region-p} for that (@pxref{The Region}).
@end defvar
@defvar activate-mark-hook
@@ -630,6 +597,23 @@
possible that the region may have changed.
@end defvar
address@hidden handle-shift-selection
+This function implements the ``shift-selection'' behavior of
+point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs
+Manual}. It is called automatically by the Emacs command loop
+whenever a command with a @samp{^} character in its @code{interactive}
+spec is invoked, before the command itself is executed
+(@pxref{Interactive Codes, ^}).
+
+If @code{shift-select-mode} is address@hidden and the current command
+was invoked via shift translation (@pxref{Key Sequence Input,
+shift-translation}), this function sets the mark and temporarily
+activates the region, unless the region was already temporarily
+activated in this way. Otherwise, if the region has been activated
+temporarily, it deactivates the mark and restores the variable
address@hidden to its earlier value.
address@hidden defun
+
@defvar mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.
@@ -650,21 +634,6 @@
@code{push-mark} discards an old mark when it adds a new one.
@end defopt
address@hidden handle-shift-selection
-This function checks whether the current command was invoked via shift
-translation (@pxref{Key Sequence Input, shift-translation}), and if
-so, sets the mark and temporarily activates the region, unless the
-region is already temporarily activated in this way. If the command
-was invoked without shift translation and the region is temporarily
-active, or if the region was activated by the mouse, the function
-deactivates the mark.
-
-This function is called whenever a command with a @samp{^} character
-in its @code{interactive} spec (@pxref{Interactive Codes, ^}) is
-invoked while @code{shift-select-mode} (@pxref{Shift Selection,,,
-emacs, The GNU Emacs Manual}) is address@hidden
address@hidden defun
-
@node The Region
@section The Region
@cindex region (between point and mark)
@@ -698,6 +667,13 @@
programs specify the bounds explicitly as arguments. (@xref{Interactive
Codes}.)
address@hidden use-region-p
+This function returns @code{t} if Transient Mark mode is enabled, the
+mark is active, and there's a valid region in the buffer. Commands
+that operate on the region (instead of on text near point) when
+there's an active mark should use this to test whether to do that.
address@hidden defun
+
@ignore
arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
@end ignore
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] emacs/doc/lispref ChangeLog markers.texi,
Chong Yidong <=