X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/409edc05695acae45695b4ea9bbb73cb7ab48f11..171920a66145032a61fab9458ec6104000ff8dd8:/lispref/markers.texi

diff --git a/lispref/markers.texi b/lispref/markers.texi
index eb576f235c..4eb34ce13a 100644
--- a/lispref/markers.texi
+++ b/lispref/markers.texi
@@ -28,10 +28,13 @@ deleted, so that it stays with the two characters on either side of it.
 @node Overview of Markers
 @section Overview of Markers
 
-  A marker specifies a buffer and a position in that buffer.  The marker
-can be used to represent a position in the functions that require one,
-just as an integer could be used.  @xref{Positions}, for a complete
-description of positions.
+  A marker specifies a buffer and a position in that buffer.  The
+marker can be used to represent a position in the functions that
+require one, just as an integer could be used.  In that case, the
+marker's buffer is normally ignored.  Of course, a marker used in this
+way usually points to a position in the buffer that the function
+operates on, but that is entirely the programmer's responsibility.
+@xref{Positions}, for a complete description of positions.
 
   A marker has two attributes: the marker position, and the marker
 buffer.  The marker position is an integer that is equivalent (at a
@@ -323,10 +326,6 @@ marker should do by setting its @dfn{insertion type}.  Note that use of
 @code{insert-before-markers} ignores markers' insertion types, always
 relocating a marker to point after the inserted text.
 
-Most functions that create markers, without explicitly specifying an
-insertion type, create them with insertion type @code{nil}.  Also, the
-mark has, by default, insertion type @code{nil}.
-
 @defun set-marker-insertion-type marker type
 This function sets the insertion type of marker @var{marker} to
 @var{type}.  If @var{type} is @code{t}, @var{marker} will advance when
@@ -338,6 +337,11 @@ text is inserted at its position.  If @var{type} is @code{nil},
 This function reports the current insertion type of @var{marker}.
 @end defun
 
+Most functions that create markers, without an argument allowing to
+specify the insertion type, create them with insertion type
+@code{nil}.  Also, the mark has, by default, insertion type
+@code{nil}.
+
 @node Moving Markers
 @section Moving Marker Positions
 
@@ -390,17 +394,17 @@ This is another name for @code{set-marker}.
 @cindex mark ring
 
   One special marker in each buffer is designated @dfn{the mark}.  It
-records a position for the user for the sake of commands such as
-@code{kill-region} 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 @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.
-
-  Many commands are designed so that when called interactively they
-operate on the text between point and the mark.  If you are writing such
-a command, don't examine the mark directly; instead, use
+specifies a position to bound a range of text for commands such as
+@code{kill-region} 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
+@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.
+
+  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
 @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
@@ -550,6 +554,12 @@ This variable if non-@code{nil} 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.
+
+Lisp programs can set @code{transient-mark-mode} to @code{only} to
+enable Transient Mark mode for the following command only.  During
+that following command, the value of @code{transient-mark-mode} is
+@code{identity}.  If it is still @code{identity} at the end of the
+command, it changes to @code{nil}.
 @end defopt
 
 @defopt mark-even-if-inactive