annotate doc/lispref/markers.texi @ 112393:f7e256e5ea88

gnus-art.el (gnus-article-remove-images, gnus-article-show-images): Widen article buffer.
author Katsumi Yamaoka <yamaoka@jpl.org>
date Fri, 21 Jan 2011 04:16:57 +0000
parents ef719132ddfa
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
112218
376148b31b5e Add 2011 to FSF/AIST copyright years.
Glenn Morris <rgm@gnu.org>
parents: 106815
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84086
diff changeset
6 @setfilename ../../info/markers
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Markers, Text, Positions, Top
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @chapter Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @cindex markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 A @dfn{marker} is a Lisp object used to specify a position in a buffer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 relative to the surrounding text. A marker changes its offset from the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 beginning of the buffer automatically whenever text is inserted or
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14 deleted, so that it stays with the two characters on either side of it.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16 @menu
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 * Overview of Markers:: The components of a marker, and how it relocates.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 * Predicates on Markers:: Testing whether an object is a marker.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 * Creating Markers:: Making empty markers or markers at certain places.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 * Information from Markers:: Finding the marker's buffer or character position.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 * Marker Insertion Types:: Two ways a marker can relocate when you
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 insert where it points.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23 * Moving Markers:: Moving the marker to a new buffer or position.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 * The Mark:: How "the mark" is implemented with a marker.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 * The Region:: How to access "the region".
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26 @end menu
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
27
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 @node Overview of Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
29 @section Overview of Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
30
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 A marker specifies a buffer and a position in that buffer. The
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 marker can be used to represent a position in the functions that
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33 require one, just as an integer could be used. In that case, the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 marker's buffer is normally ignored. Of course, a marker used in this
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 way usually points to a position in the buffer that the function
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 operates on, but that is entirely the programmer's responsibility.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 @xref{Positions}, for a complete description of positions.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
39 A marker has three attributes: the marker position, the marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40 buffer, and the insertion type. The marker position is an integer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 that is equivalent (at a given time) to the marker as a position in
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 that buffer. But the marker's position value can change often during
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43 the life of the marker. Insertion and deletion of text in the buffer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44 relocate the marker. The idea is that a marker positioned between two
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 characters remains between those two characters despite insertion and
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46 deletion elsewhere in the buffer. Relocation changes the integer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 equivalent of the marker.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49 @cindex marker relocation
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 Deleting text around a marker's position leaves the marker between the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51 characters immediately before and after the deleted text. Inserting
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 text at the position of a marker normally leaves the marker either in
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 front of or after the new text, depending on the marker's @dfn{insertion
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54 type} (@pxref{Marker Insertion Types})---unless the insertion is done
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55 with @code{insert-before-markers} (@pxref{Insertion}).
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57 @cindex marker garbage collection
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58 Insertion and deletion in a buffer must check all the markers and
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59 relocate them if necessary. This slows processing in a buffer with a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60 large number of markers. For this reason, it is a good idea to make a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 marker point nowhere if you are sure you don't need it any more.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 Unreferenced markers are garbage collected eventually, but until then
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 will continue to use time if they do point somewhere.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65 @cindex markers as numbers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66 Because it is common to perform arithmetic operations on a marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67 position, most of the arithmetic operations (including @code{+} and
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 @code{-}) accept markers as arguments. In such cases, the marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 stands for its current position.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 Here are examples of creating markers, setting markers, and moving point
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 to markers:
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76 ;; @r{Make a new marker that initially does not point anywhere:}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 (setq m1 (make-marker))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78 @result{} #<marker in no buffer>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83 ;; @r{in the current buffer:}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84 (set-marker m1 100)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 @result{} #<marker at 100 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 ;; @r{Now insert one character at the beginning of the buffer:}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90 (goto-char (point-min))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91 @result{} 1
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92 (insert "Q")
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 @result{} nil
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97 ;; @r{@code{m1} is updated appropriately.}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 m1
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99 @result{} #<marker at 101 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 ;; @r{Two markers that point to the same position}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104 ;; @r{are not @code{eq}, but they are @code{equal}.}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 (setq m2 (copy-marker m1))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 @result{} #<marker at 101 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 (eq m1 m2)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 @result{} nil
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 (equal m1 m2)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110 @result{} t
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 ;; @r{When you are finished using a marker, make it point nowhere.}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115 (set-marker m1 nil)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 @result{} #<marker in no buffer>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120 @node Predicates on Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121 @section Predicates on Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 You can test an object to see whether it is a marker, or whether it is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 either an integer or a marker. The latter test is useful in connection
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 with the arithmetic functions that work with both markers and integers.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 @defun markerp object
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 This function returns @code{t} if @var{object} is a marker, @code{nil}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129 otherwise. Note that integers are not markers, even though many
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 functions will accept either a marker or an integer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133 @defun integer-or-marker-p object
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134 This function returns @code{t} if @var{object} is an integer or a marker,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
135 @code{nil} otherwise.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
136 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
137
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138 @defun number-or-marker-p object
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 This function returns @code{t} if @var{object} is a number (either
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 integer or floating point) or a marker, @code{nil} otherwise.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 @node Creating Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 @section Functions that Create Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 When you create a new marker, you can make it point nowhere, or point
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 to the present position of point, or to the beginning or end of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 accessible portion of the buffer, or to the same place as another given
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149 marker.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 The next four functions all return markers with insertion type
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 @code{nil}. @xref{Marker Insertion Types}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154 @defun make-marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155 This function returns a newly created marker that does not point
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156 anywhere.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160 (make-marker)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 @result{} #<marker in no buffer>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166 @defun point-marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167 This function returns a new marker that points to the present position
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 of point in the current buffer. @xref{Point}. For an example, see
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 @code{copy-marker}, below.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172 @defun point-min-marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 This function returns a new marker that points to the beginning of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 accessible portion of the buffer. This will be the beginning of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 buffer unless narrowing is in effect. @xref{Narrowing}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 @defun point-max-marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 This function returns a new marker that points to the end of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 accessible portion of the buffer. This will be the end of the buffer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181 unless narrowing is in effect. @xref{Narrowing}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183 Here are examples of this function and @code{point-min-marker}, shown in
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 a buffer containing a version of the source file for the text of this
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185 chapter.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189 (point-min-marker)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 @result{} #<marker at 1 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 (point-max-marker)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192 @result{} #<marker at 15573 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196 (narrow-to-region 100 200)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @result{} nil
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 (point-min-marker)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201 @result{} #<marker at 100 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204 (point-max-marker)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205 @result{} #<marker at 200 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
206 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 @defun copy-marker marker-or-integer &optional insertion-type
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211 If passed a marker as its argument, @code{copy-marker} returns a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212 new marker that points to the same place and the same buffer as does
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 @var{marker-or-integer}. If passed an integer as its argument,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214 @code{copy-marker} returns a new marker that points to position
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 @var{marker-or-integer} in the current buffer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 The new marker's insertion type is specified by the argument
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218 @var{insertion-type}. @xref{Marker Insertion Types}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 If passed an integer argument less than 1, @code{copy-marker} returns a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 new marker that points to the beginning of the current buffer. If
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222 passed an integer argument greater than the length of the buffer,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 @code{copy-marker} returns a new marker that points to the end of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224 buffer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 (copy-marker 0)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 @result{} #<marker at 1 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 (copy-marker 20000)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234 @result{} #<marker at 7572 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238 An error is signaled if @var{marker} is neither a marker nor an
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 integer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 Two distinct markers are considered @code{equal} (even though not
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243 @code{eq}) to each other if they have the same position and buffer, or
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244 if they both point nowhere.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 (setq p (point-marker))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 @result{} #<marker at 2139 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 (setq q (copy-marker p))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 @result{} #<marker at 2139 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 (eq p q)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 @result{} nil
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263 (equal p q)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @result{} t
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268 @node Information from Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269 @section Information from Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 This section describes the functions for accessing the components of a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 marker object.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 @defun marker-position marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 This function returns the position that @var{marker} points to, or
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276 @code{nil} if it points nowhere.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 @defun marker-buffer marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 This function returns the buffer that @var{marker} points into, or
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 @code{nil} if it points nowhere.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 (setq m (make-marker))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 @result{} #<marker in no buffer>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289 (marker-position m)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 @result{} nil
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 (marker-buffer m)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294 @result{} nil
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298 (set-marker m 3770 (current-buffer))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299 @result{} #<marker at 3770 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 (marker-buffer m)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 @result{} #<buffer markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306 (marker-position m)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 @result{} 3770
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 @defun buffer-has-markers-at position
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 This function returns @code{t} if one or more markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 point at position @var{position} in the current buffer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317 @node Marker Insertion Types
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318 @section Marker Insertion Types
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
320 @cindex insertion type of a marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321 When you insert text directly at the place where a marker points,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 there are two possible ways to relocate that marker: it can point before
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323 the inserted text, or point after it. You can specify which one a given
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 marker should do by setting its @dfn{insertion type}. Note that use of
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 @code{insert-before-markers} ignores markers' insertion types, always
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 relocating a marker to point after the inserted text.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328 @defun set-marker-insertion-type marker type
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 This function sets the insertion type of marker @var{marker} to
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330 @var{type}. If @var{type} is @code{t}, @var{marker} will advance when
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 text is inserted at its position. If @var{type} is @code{nil},
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 @var{marker} does not advance when text is inserted there.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 @defun marker-insertion-type marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
336 This function reports the current insertion type of @var{marker}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 Most functions that create markers, without an argument allowing to
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340 specify the insertion type, create them with insertion type
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 @code{nil}. Also, the mark has, by default, insertion type
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342 @code{nil}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344 @node Moving Markers
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
345 @section Moving Marker Positions
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
346
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
347 This section describes how to change the position of an existing
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348 marker. When you do this, be sure you know whether the marker is used
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 outside of your program, and, if so, what effects will result from
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350 moving it---otherwise, confusing things may happen in other parts of
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351 Emacs.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 @defun set-marker marker position &optional buffer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 This function moves @var{marker} to @var{position}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355 in @var{buffer}. If @var{buffer} is not provided, it defaults to
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356 the current buffer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 to the beginning of the buffer. If @var{position} is greater than the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360 size of the buffer, @code{set-marker} moves marker to the end of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 buffer. If @var{position} is @code{nil} or a marker that points
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 nowhere, then @var{marker} is set to point nowhere.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364 The value returned is @var{marker}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 (setq m (point-marker))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369 @result{} #<marker at 4714 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 (set-marker m 55)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 @result{} #<marker at 55 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 (setq b (get-buffer "foo"))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 @result{} #<buffer foo>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380 (set-marker m 0 b)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381 @result{} #<marker at 1 in foo>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 @defun move-marker marker position &optional buffer
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 This is another name for @code{set-marker}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 @node The Mark
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391 @section The Mark
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392 @cindex mark, the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393 @cindex mark ring
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
395 Each buffer has a special marker, which is designated @dfn{the
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
396 mark}. When a buffer is newly created, this marker exists but does
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
397 not point anywhere; this means that the mark ``doesn't exist'' in that
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
398 buffer yet. Subsequent commands can set the mark.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
400 The mark specifies a position to bound a range of text for many
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
401 commands, such as @code{kill-region} and @code{indent-rigidly}. These
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
402 commands typically act on the text between point and the mark, which
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
403 is called the @dfn{region}. If you are writing a command that
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
404 operates on the region, don't examine the mark directly; instead, use
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405 @code{interactive} with the @samp{r} specification. This provides the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406 values of point and the mark as arguments to the command in an
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 interactive call, but permits other Lisp programs to specify arguments
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 explicitly. @xref{Interactive Codes}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
410 Some commands set the mark as a side-effect. Commands should do
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
411 this only if it has a potential use to the user, and never for their
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
412 own internal purposes. For example, the @code{replace-regexp} command
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
413 sets the mark to the value of point before doing any replacements,
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
414 because this enables the user to move back there conveniently after
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
415 the replace is finished.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417 Once the mark ``exists'' in a buffer, it normally never ceases to
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
418 exist. However, it may become @dfn{inactive}, if Transient Mark mode
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
419 is enabled. The buffer-local variable @code{mark-active}, if
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
420 non-@code{nil}, means that the mark is active. A command can call the
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
421 function @code{deactivate-mark} to deactivate the mark directly, or it
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
422 can request deactivation of the mark upon return to the editor command
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
423 loop by setting the variable @code{deactivate-mark} to a
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
424 non-@code{nil} value.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
426 If Transient Mode is enabled, certain editing commands that normally
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
427 apply to text near point, apply instead to the region when the mark is
98784
ae2c057fb447 (The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents: 98762
diff changeset
428 active. This is the main motivation for using Transient Mark mode.
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
429 (Another is that this enables highlighting of the region when the mark
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
430 is active. @xref{Display}.)
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
432 In addition to the mark, each buffer has a @dfn{mark ring} which is a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433 list of markers containing previous values of the mark. When editing
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434 commands change the mark, they should normally save the old value of the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435 mark on the mark ring. The variable @code{mark-ring-max} specifies the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 maximum number of entries in the mark ring; once the list becomes this
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 long, adding a new element deletes the last element.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439 There is also a separate global mark ring, but that is used only in a
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440 few particular user-level commands, and is not relevant to Lisp
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 programming. So we do not describe it here.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 @defun mark &optional force
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444 @cindex current buffer mark
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 This function returns the current buffer's mark position as an integer,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446 or @code{nil} if no mark has ever been set in this buffer.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449 @code{nil}, @code{mark} signals an error if the mark is inactive.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450 However, if @var{force} is non-@code{nil}, then @code{mark} disregards
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
451 inactivity of the mark, and returns the mark position (or @code{nil})
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
452 anyway.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455 @defun mark-marker
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 This function returns the marker that represents the current buffer's
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457 mark. It is not a copy, it is the marker used internally. Therefore,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 changing this marker's position will directly affect the buffer's
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459 mark. Don't do that unless that is the effect you want.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463 (setq m (mark-marker))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 @result{} #<marker at 3420 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467 (set-marker m 100)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 @result{} #<marker at 100 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 (mark-marker)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472 @result{} #<marker at 100 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 Like any marker, this marker can be set to point at any buffer you
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477 like. If you make it point at any buffer other than the one of which
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 it is the mark, it will yield perfectly consistent, but rather odd,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479 results. We recommend that you not do it!
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482 @defun set-mark position
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 This function sets the mark to @var{position}, and activates the mark.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484 The old value of the mark is @emph{not} pushed onto the mark ring.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486 @strong{Please note:} Use this function only if you want the user to
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 see that the mark has moved, and you want the previous mark position to
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488 be lost. Normally, when a new mark is set, the old one should go on the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489 @code{mark-ring}. For this reason, most applications should use
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 Novice Emacs Lisp programmers often try to use the mark for the wrong
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493 purposes. The mark saves a location for the user's convenience. An
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494 editing command should not alter the mark unless altering the mark is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
495 part of the user-level functionality of the command. (And, in that
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
496 case, this effect should be documented.) To remember a location for
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
497 internal use in the Lisp program, store it in a Lisp variable. For
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498 example:
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 (let ((beg (point)))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
503 (forward-line 1)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
504 (delete-region beg (point))).
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
505 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
506 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 @defun push-mark &optional position nomsg activate
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 This function sets the current buffer's mark to @var{position}, and
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 pushes a copy of the previous mark onto @code{mark-ring}. If
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 @var{position} is @code{nil}, then the value of point is used.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513 @code{push-mark} returns @code{nil}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 The function @code{push-mark} normally @emph{does not} activate the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516 mark. To do that, specify @code{t} for the argument @var{activate}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 A @samp{Mark set} message is displayed unless @var{nomsg} is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519 non-@code{nil}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 @defun pop-mark
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 This function pops off the top element of @code{mark-ring} and makes
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524 that mark become the buffer's actual mark. This does not move point in
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525 the buffer, and it does nothing if @code{mark-ring} is empty. It
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 deactivates the mark.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528 The return value is not meaningful.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 @defopt transient-mark-mode
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
532 This variable, if non-@code{nil}, enables Transient Mark mode. In
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
533 Transient Mark mode, every buffer-modifying primitive sets
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
534 @code{deactivate-mark}. As a consequence, most commands that modify
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
535 the buffer also deactivate the mark.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
537 When Transient Mark mode is enabled and the mark is active, many
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
538 commands that normally apply to the text near point instead apply to
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
539 the region. Such commands should use the function @code{use-region-p}
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
540 to test whether they should operate on the region. @xref{The Region}.
98784
ae2c057fb447 (The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents: 98762
diff changeset
541
98752
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
542 Lisp programs can set @code{transient-mark-mode} to non-@code{nil},
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
543 non-@code{t} values to enable Transient Mark mode temporarily. If the
98762
ef39b163f82b (The Mark): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 98752
diff changeset
544 value is @code{lambda}, Transient Mark mode is automatically turned
98752
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
545 off after any action, such as buffer modification, that would normally
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
546 deactivate the mark. If the value is @w{@code{(only . @var{oldval})}},
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
547 then @code{transient-mark-mode} is set to the value @var{oldval} after
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
548 any subsequent command that moves point and is not shift-translated
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
549 (@pxref{Key Sequence Input, shift-translation}), or after any other
1d0213f6230f (The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents: 87649
diff changeset
550 action that would normally deactivate the mark.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 @end defopt
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 @defopt mark-even-if-inactive
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 If this is non-@code{nil}, Lisp programs and the Emacs user can use the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 mark even when it is inactive. This option affects the behavior of
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 Transient Mark mode. When the option is non-@code{nil}, deactivation of
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557 the mark turns off region highlighting, but commands that use the mark
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558 behave as if the mark were still active.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559 @end defopt
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561 @defvar deactivate-mark
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 If an editor command sets this variable non-@code{nil}, then the editor
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 command loop deactivates the mark after the command returns (if
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 Transient Mark mode is enabled). All the primitives that change the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 buffer set @code{deactivate-mark}, to deactivate the mark when the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 command is finished.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568 To write Lisp code that modifies the buffer without causing
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569 deactivation of the mark at the end of the command, bind
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 @code{deactivate-mark} to @code{nil} around the code that does the
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 modification. For example:
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574 (let (deactivate-mark)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 (insert " "))
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 @end defvar
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578
103894
60606ee8aee7 * markers.texi (The Mark): Document optional arg to deactivate-mark.
Chong Yidong <cyd@stupidchicken.com>
parents: 102855
diff changeset
579 @defun deactivate-mark &optional force
103895
8f9899f50e02 Clarify last change.
Chong Yidong <cyd@stupidchicken.com>
parents: 103894
diff changeset
580 If Transient Mark mode is enabled or @var{force} is non-@code{nil},
8f9899f50e02 Clarify last change.
Chong Yidong <cyd@stupidchicken.com>
parents: 103894
diff changeset
581 this function deactivates the mark and runs the normal hook
8f9899f50e02 Clarify last change.
Chong Yidong <cyd@stupidchicken.com>
parents: 103894
diff changeset
582 @code{deactivate-mark-hook}. Otherwise, it does nothing.
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 @defvar mark-active
98784
ae2c057fb447 (The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents: 98762
diff changeset
586 The mark is active when this variable is non-@code{nil}. This
ae2c057fb447 (The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents: 98762
diff changeset
587 variable is always buffer-local in each buffer. Do @emph{not} use the
ae2c057fb447 (The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents: 98762
diff changeset
588 value of this variable to decide whether a command that normally
ae2c057fb447 (The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents: 98762
diff changeset
589 operates on text near point should operate on the region instead. Use
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
590 the function @code{use-region-p} for that (@pxref{The Region}).
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 @end defvar
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593 @defvar activate-mark-hook
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 @defvarx deactivate-mark-hook
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595 These normal hooks are run, respectively, when the mark becomes active
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596 and when it becomes inactive. The hook @code{activate-mark-hook} is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
597 also run at the end of a command if the mark is active and it is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598 possible that the region may have changed.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599 @end defvar
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
600
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
601 @defun handle-shift-selection
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
602 This function implements the ``shift-selection'' behavior of
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
603 point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
604 Manual}. It is called automatically by the Emacs command loop
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
605 whenever a command with a @samp{^} character in its @code{interactive}
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
606 spec is invoked, before the command itself is executed
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
607 (@pxref{Interactive Codes, ^}).
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
608
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
609 If @code{shift-select-mode} is non-@code{nil} and the current command
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
610 was invoked via shift translation (@pxref{Key Sequence Input,
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
611 shift-translation}), this function sets the mark and temporarily
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
612 activates the region, unless the region was already temporarily
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
613 activated in this way. Otherwise, if the region has been activated
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
614 temporarily, it deactivates the mark and restores the variable
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
615 @code{transient-mark-mode} to its earlier value.
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
616 @end defun
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
617
84086
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 @defvar mark-ring
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619 The value of this buffer-local variable is the list of saved former
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 marks of the current buffer, most recent first.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 @example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623 @group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 mark-ring
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 @result{} (#<marker at 11050 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 #<marker at 10832 in markers.texi>
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627 @dots{})
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 @end group
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629 @end example
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 @end defvar
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 @defopt mark-ring-max
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 The value of this variable is the maximum size of @code{mark-ring}. If
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 more marks than this are pushed onto the @code{mark-ring},
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 @code{push-mark} discards an old mark when it adds a new one.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636 @end defopt
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 @node The Region
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 @section The Region
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 @cindex region (between point and mark)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 The text between point and the mark is known as @dfn{the region}.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643 Various functions operate on text delimited by point and the mark, but
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 only those functions specifically related to the region itself are
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645 described here.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 The next two functions signal an error if the mark does not point
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648 anywhere. If Transient Mark mode is enabled and
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 @code{mark-even-if-inactive} is @code{nil}, they also signal an error
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 if the mark is inactive.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652 @defun region-beginning
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653 This function returns the position of the beginning of the region (as
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 an integer). This is the position of either point or the mark,
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655 whichever is smaller.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 @defun region-end
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 This function returns the position of the end of the region (as an
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660 integer). This is the position of either point or the mark, whichever is
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 larger.
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662 @end defun
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 Few programs need to use the @code{region-beginning} and
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 @code{region-end} functions. A command designed to operate on a region
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666 should normally use @code{interactive} with the @samp{r} specification
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 to find the beginning and end of the region. This lets other Lisp
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 programs specify the bounds explicitly as arguments. (@xref{Interactive
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 Codes}.)
1ddaa60edeb3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670
102855
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
671 @defun use-region-p
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
672 This function returns @code{t} if Transient Mark mode is enabled, the
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
673 mark is active, and there's a valid region in the buffer. Commands
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
674 that operate on the region (instead of on text near point) when
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
675 there's an active mark should use this to test whether to do that.
17ba809d0f96 * markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents: 102739
diff changeset
676 @end defun