annotate man/killing.texi @ 30973:2f3dc355bcaf

(lface_equal_p): Compare strings differently. (Qtty_color_alist, Vtty_defined_color_alist): New variables. (realize_tty_face): Use them. (syms_of_xfaces): Initialize new variables. (map_tty_color): New function, extracted from realize_tty_face. (map_tty_color) [MSDOS || WINDOWSNT]: If using the frame's default foreground or background color, store the new color name in the realized face; previous code trying to do this had no effect. (realize_tty_face): Use map_tty_color. (Fclear_face_cache): Set face_change_count and ensure thorough redisplay.
author Gerd Moellmann <gerd@gnu.org>
date Sun, 20 Aug 2000 13:23:01 +0000
parents 2921bb6221db
children 7d3fd66a3ac3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
27749
986871288b53 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 25829
diff changeset
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000 Free Software Foundation, Inc.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @chapter Killing and Moving Text
Dave Love <fx@gnu.org>
parents:
diff changeset
6
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @dfn{Killing} means erasing text and copying it into the @dfn{kill
Dave Love <fx@gnu.org>
parents:
diff changeset
8 ring}, from which it can be retrieved by @dfn{yanking} it. Some systems
Dave Love <fx@gnu.org>
parents:
diff changeset
9 use the terms ``cutting'' and ``pasting'' for these operations.
Dave Love <fx@gnu.org>
parents:
diff changeset
10
Dave Love <fx@gnu.org>
parents:
diff changeset
11 The commonest way of moving or copying text within Emacs is to kill it
Dave Love <fx@gnu.org>
parents:
diff changeset
12 and later yank it elsewhere in one or more places. This is very safe
Dave Love <fx@gnu.org>
parents:
diff changeset
13 because Emacs remembers several recent kills, not just the last one. It
Dave Love <fx@gnu.org>
parents:
diff changeset
14 is versatile, because the many commands for killing syntactic units can
Dave Love <fx@gnu.org>
parents:
diff changeset
15 also be used for moving those units. But there are other ways of
Dave Love <fx@gnu.org>
parents:
diff changeset
16 copying text for special purposes.
Dave Love <fx@gnu.org>
parents:
diff changeset
17
Dave Love <fx@gnu.org>
parents:
diff changeset
18 Emacs has only one kill ring for all buffers, so you can kill text in
Dave Love <fx@gnu.org>
parents:
diff changeset
19 one buffer and yank it in another buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
20
Dave Love <fx@gnu.org>
parents:
diff changeset
21 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
22
Dave Love <fx@gnu.org>
parents:
diff changeset
23 @node Killing, Yanking, Mark, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
24 @section Deletion and Killing
Dave Love <fx@gnu.org>
parents:
diff changeset
25
Dave Love <fx@gnu.org>
parents:
diff changeset
26 @cindex killing text
Dave Love <fx@gnu.org>
parents:
diff changeset
27 @cindex cutting text
Dave Love <fx@gnu.org>
parents:
diff changeset
28 @cindex deletion
Dave Love <fx@gnu.org>
parents:
diff changeset
29 Most commands which erase text from the buffer save it in the kill
Dave Love <fx@gnu.org>
parents:
diff changeset
30 ring so that you can move or copy it to other parts of the buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
31 These commands are known as @dfn{kill} commands. The rest of the
Dave Love <fx@gnu.org>
parents:
diff changeset
32 commands that erase text do not save it in the kill ring; they are known
Dave Love <fx@gnu.org>
parents:
diff changeset
33 as @dfn{delete} commands. (This distinction is made only for erasure of
Dave Love <fx@gnu.org>
parents:
diff changeset
34 text in the buffer.) If you do a kill or delete command by mistake, you
Dave Love <fx@gnu.org>
parents:
diff changeset
35 can use the @kbd{C-x u} (@code{undo}) command to undo it
Dave Love <fx@gnu.org>
parents:
diff changeset
36 (@pxref{Undo}).
Dave Love <fx@gnu.org>
parents:
diff changeset
37
30771
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
38 @vindex kill-read-only-ok
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
39 @cindex read-only text, killing
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
40 By default, Emacs does not allow to kill text in read-only buffers.
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
41 Setting the variable @code{kill-read-only-ok} to a non-@code{nil} value
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
42 overrides that. To alert you to the fact that you killed read-only
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
43 text, Emacs prints a message to that effect in the echo area.
e9948dd313fa (Killing): Document kill-read-only-ok.
Eli Zaretskii <eliz@gnu.org>
parents: 27749
diff changeset
44
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
45 The delete commands include @kbd{C-d} (@code{delete-char}) and
Dave Love <fx@gnu.org>
parents:
diff changeset
46 @key{DEL} (@code{delete-backward-char}), which delete only one character at
Dave Love <fx@gnu.org>
parents:
diff changeset
47 a time, and those commands that delete only spaces or newlines. Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
48 that can destroy significant amounts of nontrivial data generally kill.
Dave Love <fx@gnu.org>
parents:
diff changeset
49 The commands' names and individual descriptions use the words @samp{kill}
Dave Love <fx@gnu.org>
parents:
diff changeset
50 and @samp{delete} to say which they do.
Dave Love <fx@gnu.org>
parents:
diff changeset
51
30865
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
52 @cindex Delete Selection mode
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
53 @cindex mode, Delete Selection
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
54 @findex delete-selection-mode
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
55 You can arrange for selected text to be killed when you insert something
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
56 and replaced by what you insert; this is the way many text interfaces
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
57 work. To do this turn on Delete Selection mode. with @kbd{M-x
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
58 delete-selection-mode} or using Custom. Also in Delete Selection mode
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
59 @key{DEL}, @kbd{C-d} and some other keys will just kill the whole
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
60 selection and Transient Mark mode is turned on (@pxref{Transient Mark}).
fb3d8e6e0497 delete-selection-mode
Dave Love <fx@gnu.org>
parents: 30771
diff changeset
61
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
62 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
63 * Deletion:: Commands for deleting small amounts of text and
Dave Love <fx@gnu.org>
parents:
diff changeset
64 blank areas.
Dave Love <fx@gnu.org>
parents:
diff changeset
65 * Killing by Lines:: How to kill entire lines of text at one time.
Dave Love <fx@gnu.org>
parents:
diff changeset
66 * Other Kill Commands:: Commands to kill large regions of text and
Dave Love <fx@gnu.org>
parents:
diff changeset
67 syntactic units such as words and sentences.
Dave Love <fx@gnu.org>
parents:
diff changeset
68 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
69
Dave Love <fx@gnu.org>
parents:
diff changeset
70 @node Deletion
Dave Love <fx@gnu.org>
parents:
diff changeset
71 @subsection Deletion
Dave Love <fx@gnu.org>
parents:
diff changeset
72 @c ??? Should be backward-delete-char
Dave Love <fx@gnu.org>
parents:
diff changeset
73 @findex delete-backward-char
Dave Love <fx@gnu.org>
parents:
diff changeset
74 @findex delete-char
Dave Love <fx@gnu.org>
parents:
diff changeset
75 @kindex DEL
Dave Love <fx@gnu.org>
parents:
diff changeset
76 @kindex C-d
Dave Love <fx@gnu.org>
parents:
diff changeset
77
Dave Love <fx@gnu.org>
parents:
diff changeset
78 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
79 @item C-d
Dave Love <fx@gnu.org>
parents:
diff changeset
80 Delete next character (@code{delete-char}).
Dave Love <fx@gnu.org>
parents:
diff changeset
81 @item @key{DEL}
Dave Love <fx@gnu.org>
parents:
diff changeset
82 Delete previous character (@code{delete-backward-char}).
Dave Love <fx@gnu.org>
parents:
diff changeset
83 @item M-\
Dave Love <fx@gnu.org>
parents:
diff changeset
84 Delete spaces and tabs around point (@code{delete-horizontal-space}).
Dave Love <fx@gnu.org>
parents:
diff changeset
85 @item M-@key{SPC}
Dave Love <fx@gnu.org>
parents:
diff changeset
86 Delete spaces and tabs around point, leaving one space
Dave Love <fx@gnu.org>
parents:
diff changeset
87 (@code{just-one-space}).
Dave Love <fx@gnu.org>
parents:
diff changeset
88 @item C-x C-o
Dave Love <fx@gnu.org>
parents:
diff changeset
89 Delete blank lines around the current line (@code{delete-blank-lines}).
Dave Love <fx@gnu.org>
parents:
diff changeset
90 @item M-^
Dave Love <fx@gnu.org>
parents:
diff changeset
91 Join two lines by deleting the intervening newline, along with any
Dave Love <fx@gnu.org>
parents:
diff changeset
92 indentation following it (@code{delete-indentation}).
Dave Love <fx@gnu.org>
parents:
diff changeset
93 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
94
Dave Love <fx@gnu.org>
parents:
diff changeset
95 The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
Dave Love <fx@gnu.org>
parents:
diff changeset
96 @key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the
Dave Love <fx@gnu.org>
parents:
diff changeset
97 character after point, the one the cursor is ``on top of.'' This
Dave Love <fx@gnu.org>
parents:
diff changeset
98 doesn't move point. @key{DEL} deletes the character before the cursor,
Dave Love <fx@gnu.org>
parents:
diff changeset
99 and moves point back. You can delete newlines like any other characters
Dave Love <fx@gnu.org>
parents:
diff changeset
100 in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d}
Dave Love <fx@gnu.org>
parents:
diff changeset
101 and @key{DEL} aren't always delete commands; when given arguments, they
Dave Love <fx@gnu.org>
parents:
diff changeset
102 kill instead, since they can erase more than one character this way.
Dave Love <fx@gnu.org>
parents:
diff changeset
103
Dave Love <fx@gnu.org>
parents:
diff changeset
104 @kindex M-\
Dave Love <fx@gnu.org>
parents:
diff changeset
105 @findex delete-horizontal-space
Dave Love <fx@gnu.org>
parents:
diff changeset
106 @kindex M-SPC
Dave Love <fx@gnu.org>
parents:
diff changeset
107 @findex just-one-space
Dave Love <fx@gnu.org>
parents:
diff changeset
108 The other delete commands are those which delete only whitespace
Dave Love <fx@gnu.org>
parents:
diff changeset
109 characters: spaces, tabs and newlines. @kbd{M-\}
Dave Love <fx@gnu.org>
parents:
diff changeset
110 (@code{delete-horizontal-space}) deletes all the spaces and tab
Dave Love <fx@gnu.org>
parents:
diff changeset
111 characters before and after point. @kbd{M-@key{SPC}}
Dave Love <fx@gnu.org>
parents:
diff changeset
112 (@code{just-one-space}) does likewise but leaves a single space after
Dave Love <fx@gnu.org>
parents:
diff changeset
113 point, regardless of the number of spaces that existed previously (even
Dave Love <fx@gnu.org>
parents:
diff changeset
114 zero).
Dave Love <fx@gnu.org>
parents:
diff changeset
115
Dave Love <fx@gnu.org>
parents:
diff changeset
116 @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines
Dave Love <fx@gnu.org>
parents:
diff changeset
117 after the current line. If the current line is blank, it deletes all
Dave Love <fx@gnu.org>
parents:
diff changeset
118 blank lines preceding the current line as well (leaving one blank line,
Dave Love <fx@gnu.org>
parents:
diff changeset
119 the current line).
Dave Love <fx@gnu.org>
parents:
diff changeset
120
Dave Love <fx@gnu.org>
parents:
diff changeset
121 @kbd{M-^} (@code{delete-indentation}) joins the current line and the
Dave Love <fx@gnu.org>
parents:
diff changeset
122 previous line, by deleting a newline and all surrounding spaces, usually
Dave Love <fx@gnu.org>
parents:
diff changeset
123 leaving a single space. @xref{Indentation,M-^}.
Dave Love <fx@gnu.org>
parents:
diff changeset
124
Dave Love <fx@gnu.org>
parents:
diff changeset
125 @node Killing by Lines
Dave Love <fx@gnu.org>
parents:
diff changeset
126 @subsection Killing by Lines
Dave Love <fx@gnu.org>
parents:
diff changeset
127
Dave Love <fx@gnu.org>
parents:
diff changeset
128 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
129 @item C-k
Dave Love <fx@gnu.org>
parents:
diff changeset
130 Kill rest of line or one or more lines (@code{kill-line}).
Dave Love <fx@gnu.org>
parents:
diff changeset
131 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
132
Dave Love <fx@gnu.org>
parents:
diff changeset
133 @kindex C-k
Dave Love <fx@gnu.org>
parents:
diff changeset
134 @findex kill-line
Dave Love <fx@gnu.org>
parents:
diff changeset
135 The simplest kill command is @kbd{C-k}. If given at the beginning of
Dave Love <fx@gnu.org>
parents:
diff changeset
136 a line, it kills all the text on the line, leaving it blank. When used
Dave Love <fx@gnu.org>
parents:
diff changeset
137 on a blank line, it kills the whole line including its newline. To kill
Dave Love <fx@gnu.org>
parents:
diff changeset
138 an entire non-blank line, go to the beginning and type @kbd{C-k} twice.
Dave Love <fx@gnu.org>
parents:
diff changeset
139
Dave Love <fx@gnu.org>
parents:
diff changeset
140 More generally, @kbd{C-k} kills from point up to the end of the line,
Dave Love <fx@gnu.org>
parents:
diff changeset
141 unless it is at the end of a line. In that case it kills the newline
Dave Love <fx@gnu.org>
parents:
diff changeset
142 following point, thus merging the next line into the current one.
Dave Love <fx@gnu.org>
parents:
diff changeset
143 Spaces and tabs that you can't see at the end of the line are ignored
Dave Love <fx@gnu.org>
parents:
diff changeset
144 when deciding which case applies, so if point appears to be at the end
Dave Love <fx@gnu.org>
parents:
diff changeset
145 of the line, you can be sure @kbd{C-k} will kill the newline.
Dave Love <fx@gnu.org>
parents:
diff changeset
146
Dave Love <fx@gnu.org>
parents:
diff changeset
147 When @kbd{C-k} is given a positive argument, it kills that many lines
Dave Love <fx@gnu.org>
parents:
diff changeset
148 and the newlines that follow them (however, text on the current line
Dave Love <fx@gnu.org>
parents:
diff changeset
149 before point is spared). With a negative argument @minus{}@var{n}, it
Dave Love <fx@gnu.org>
parents:
diff changeset
150 kills @var{n} lines preceding the current line (together with the text
Dave Love <fx@gnu.org>
parents:
diff changeset
151 on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front
Dave Love <fx@gnu.org>
parents:
diff changeset
152 of a line kills the two previous lines.
Dave Love <fx@gnu.org>
parents:
diff changeset
153
Dave Love <fx@gnu.org>
parents:
diff changeset
154 @kbd{C-k} with an argument of zero kills the text before point on the
Dave Love <fx@gnu.org>
parents:
diff changeset
155 current line.
Dave Love <fx@gnu.org>
parents:
diff changeset
156
Dave Love <fx@gnu.org>
parents:
diff changeset
157 @vindex kill-whole-line
Dave Love <fx@gnu.org>
parents:
diff changeset
158 If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at
Dave Love <fx@gnu.org>
parents:
diff changeset
159 the very beginning of a line kills the entire line including the
Dave Love <fx@gnu.org>
parents:
diff changeset
160 following newline. This variable is normally @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
161
Dave Love <fx@gnu.org>
parents:
diff changeset
162 @node Other Kill Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
163 @subsection Other Kill Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
164 @findex kill-region
Dave Love <fx@gnu.org>
parents:
diff changeset
165 @kindex C-w
Dave Love <fx@gnu.org>
parents:
diff changeset
166
Dave Love <fx@gnu.org>
parents:
diff changeset
167 @c DoubleWideCommands
Dave Love <fx@gnu.org>
parents:
diff changeset
168 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
169 @item C-w
Dave Love <fx@gnu.org>
parents:
diff changeset
170 Kill region (from point to the mark) (@code{kill-region}).
Dave Love <fx@gnu.org>
parents:
diff changeset
171 @item M-d
Dave Love <fx@gnu.org>
parents:
diff changeset
172 Kill word (@code{kill-word}). @xref{Words}.
Dave Love <fx@gnu.org>
parents:
diff changeset
173 @item M-@key{DEL}
Dave Love <fx@gnu.org>
parents:
diff changeset
174 Kill word backwards (@code{backward-kill-word}).
Dave Love <fx@gnu.org>
parents:
diff changeset
175 @item C-x @key{DEL}
Dave Love <fx@gnu.org>
parents:
diff changeset
176 Kill back to beginning of sentence (@code{backward-kill-sentence}).
Dave Love <fx@gnu.org>
parents:
diff changeset
177 @xref{Sentences}.
Dave Love <fx@gnu.org>
parents:
diff changeset
178 @item M-k
Dave Love <fx@gnu.org>
parents:
diff changeset
179 Kill to end of sentence (@code{kill-sentence}).
Dave Love <fx@gnu.org>
parents:
diff changeset
180 @item C-M-k
Dave Love <fx@gnu.org>
parents:
diff changeset
181 Kill sexp (@code{kill-sexp}). @xref{Lists}.
Dave Love <fx@gnu.org>
parents:
diff changeset
182 @item M-z @var{char}
Dave Love <fx@gnu.org>
parents:
diff changeset
183 Kill through the next occurrence of @var{char} (@code{zap-to-char}).
Dave Love <fx@gnu.org>
parents:
diff changeset
184 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
185
Dave Love <fx@gnu.org>
parents:
diff changeset
186 A kill command which is very general is @kbd{C-w}
Dave Love <fx@gnu.org>
parents:
diff changeset
187 (@code{kill-region}), which kills everything between point and the
Dave Love <fx@gnu.org>
parents:
diff changeset
188 mark. With this command, you can kill any contiguous sequence of
Dave Love <fx@gnu.org>
parents:
diff changeset
189 characters, if you first set the region around them.
Dave Love <fx@gnu.org>
parents:
diff changeset
190
Dave Love <fx@gnu.org>
parents:
diff changeset
191 @kindex M-z
Dave Love <fx@gnu.org>
parents:
diff changeset
192 @findex zap-to-char
Dave Love <fx@gnu.org>
parents:
diff changeset
193 A convenient way of killing is combined with searching: @kbd{M-z}
Dave Love <fx@gnu.org>
parents:
diff changeset
194 (@code{zap-to-char}) reads a character and kills from point up to (and
Dave Love <fx@gnu.org>
parents:
diff changeset
195 including) the next occurrence of that character in the buffer. A
Dave Love <fx@gnu.org>
parents:
diff changeset
196 numeric argument acts as a repeat count. A negative argument means to
Dave Love <fx@gnu.org>
parents:
diff changeset
197 search backward and kill text before point.
Dave Love <fx@gnu.org>
parents:
diff changeset
198
Dave Love <fx@gnu.org>
parents:
diff changeset
199 Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
Dave Love <fx@gnu.org>
parents:
diff changeset
200 @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
Dave Love <fx@gnu.org>
parents:
diff changeset
201 sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
Dave Love <fx@gnu.org>
parents:
diff changeset
202 (@pxref{Sentences}).@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
203
Dave Love <fx@gnu.org>
parents:
diff changeset
204 You can use kill commands in read-only buffers. They don't actually
Dave Love <fx@gnu.org>
parents:
diff changeset
205 change the buffer, and they beep to warn you of that, but they do copy
Dave Love <fx@gnu.org>
parents:
diff changeset
206 the text you tried to kill into the kill ring, so you can yank it into
Dave Love <fx@gnu.org>
parents:
diff changeset
207 other buffers. Most of the kill commands move point across the text
Dave Love <fx@gnu.org>
parents:
diff changeset
208 they copy in this way, so that successive kill commands build up a
Dave Love <fx@gnu.org>
parents:
diff changeset
209 single kill ring entry as usual.
Dave Love <fx@gnu.org>
parents:
diff changeset
210
Dave Love <fx@gnu.org>
parents:
diff changeset
211 @node Yanking, Accumulating Text, Killing, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
212 @section Yanking
Dave Love <fx@gnu.org>
parents:
diff changeset
213 @cindex moving text
Dave Love <fx@gnu.org>
parents:
diff changeset
214 @cindex copying text
Dave Love <fx@gnu.org>
parents:
diff changeset
215 @cindex kill ring
Dave Love <fx@gnu.org>
parents:
diff changeset
216 @cindex yanking
Dave Love <fx@gnu.org>
parents:
diff changeset
217 @cindex pasting
Dave Love <fx@gnu.org>
parents:
diff changeset
218
Dave Love <fx@gnu.org>
parents:
diff changeset
219 @dfn{Yanking} means reinserting text previously killed. This is what
Dave Love <fx@gnu.org>
parents:
diff changeset
220 some systems call ``pasting.'' The usual way to move or copy text is to
Dave Love <fx@gnu.org>
parents:
diff changeset
221 kill it and then yank it elsewhere one or more times.
Dave Love <fx@gnu.org>
parents:
diff changeset
222
Dave Love <fx@gnu.org>
parents:
diff changeset
223 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
224 @item C-y
Dave Love <fx@gnu.org>
parents:
diff changeset
225 Yank last killed text (@code{yank}).
Dave Love <fx@gnu.org>
parents:
diff changeset
226 @item M-y
Dave Love <fx@gnu.org>
parents:
diff changeset
227 Replace text just yanked with an earlier batch of killed text
Dave Love <fx@gnu.org>
parents:
diff changeset
228 (@code{yank-pop}).
Dave Love <fx@gnu.org>
parents:
diff changeset
229 @item M-w
Dave Love <fx@gnu.org>
parents:
diff changeset
230 Save region as last killed text without actually killing it
Dave Love <fx@gnu.org>
parents:
diff changeset
231 (@code{kill-ring-save}).
Dave Love <fx@gnu.org>
parents:
diff changeset
232 @item C-M-w
Dave Love <fx@gnu.org>
parents:
diff changeset
233 Append next kill to last batch of killed text (@code{append-next-kill}).
Dave Love <fx@gnu.org>
parents:
diff changeset
234 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
235
Dave Love <fx@gnu.org>
parents:
diff changeset
236 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
237 * Kill Ring:: Where killed text is stored. Basic yanking.
Dave Love <fx@gnu.org>
parents:
diff changeset
238 * Appending Kills:: Several kills in a row all yank together.
Dave Love <fx@gnu.org>
parents:
diff changeset
239 * Earlier Kills:: Yanking something killed some time ago.
Dave Love <fx@gnu.org>
parents:
diff changeset
240 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
241
Dave Love <fx@gnu.org>
parents:
diff changeset
242 @node Kill Ring
Dave Love <fx@gnu.org>
parents:
diff changeset
243 @subsection The Kill Ring
Dave Love <fx@gnu.org>
parents:
diff changeset
244
Dave Love <fx@gnu.org>
parents:
diff changeset
245 All killed text is recorded in the @dfn{kill ring}, a list of blocks of
Dave Love <fx@gnu.org>
parents:
diff changeset
246 text that have been killed. There is only one kill ring, shared by all
Dave Love <fx@gnu.org>
parents:
diff changeset
247 buffers, so you can kill text in one buffer and yank it in another buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
248 This is the usual way to move text from one file to another.
Dave Love <fx@gnu.org>
parents:
diff changeset
249 (@xref{Accumulating Text}, for some other ways.)
Dave Love <fx@gnu.org>
parents:
diff changeset
250
Dave Love <fx@gnu.org>
parents:
diff changeset
251 @kindex C-y
Dave Love <fx@gnu.org>
parents:
diff changeset
252 @findex yank
Dave Love <fx@gnu.org>
parents:
diff changeset
253 The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
Dave Love <fx@gnu.org>
parents:
diff changeset
254 kill. It leaves the cursor at the end of the text. It sets the mark at
Dave Love <fx@gnu.org>
parents:
diff changeset
255 the beginning of the text. @xref{Mark}.
Dave Love <fx@gnu.org>
parents:
diff changeset
256
Dave Love <fx@gnu.org>
parents:
diff changeset
257 @kbd{C-u C-y} leaves the cursor in front of the text, and sets the
Dave Love <fx@gnu.org>
parents:
diff changeset
258 mark after it. This happens only if the argument is specified with just
Dave Love <fx@gnu.org>
parents:
diff changeset
259 a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u}
Dave Love <fx@gnu.org>
parents:
diff changeset
260 and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}).
Dave Love <fx@gnu.org>
parents:
diff changeset
261
Dave Love <fx@gnu.org>
parents:
diff changeset
262 @kindex M-w
Dave Love <fx@gnu.org>
parents:
diff changeset
263 @findex kill-ring-save
Dave Love <fx@gnu.org>
parents:
diff changeset
264 To copy a block of text, you can use @kbd{M-w}
Dave Love <fx@gnu.org>
parents:
diff changeset
265 (@code{kill-ring-save}), which copies the region into the kill ring
Dave Love <fx@gnu.org>
parents:
diff changeset
266 without removing it from the buffer. This is approximately equivalent
Dave Love <fx@gnu.org>
parents:
diff changeset
267 to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not
Dave Love <fx@gnu.org>
parents:
diff changeset
268 alter the undo history and does not temporarily change the screen.
Dave Love <fx@gnu.org>
parents:
diff changeset
269
Dave Love <fx@gnu.org>
parents:
diff changeset
270 @node Appending Kills
Dave Love <fx@gnu.org>
parents:
diff changeset
271 @subsection Appending Kills
Dave Love <fx@gnu.org>
parents:
diff changeset
272
Dave Love <fx@gnu.org>
parents:
diff changeset
273 @cindex appending kills in the ring
Dave Love <fx@gnu.org>
parents:
diff changeset
274 @cindex television
Dave Love <fx@gnu.org>
parents:
diff changeset
275 Normally, each kill command pushes a new entry onto the kill ring.
Dave Love <fx@gnu.org>
parents:
diff changeset
276 However, two or more kill commands in a row combine their text into a
Dave Love <fx@gnu.org>
parents:
diff changeset
277 single entry, so that a single @kbd{C-y} yanks all the text as a unit,
Dave Love <fx@gnu.org>
parents:
diff changeset
278 just as it was before it was killed.
Dave Love <fx@gnu.org>
parents:
diff changeset
279
Dave Love <fx@gnu.org>
parents:
diff changeset
280 Thus, if you want to yank text as a unit, you need not kill all of it
Dave Love <fx@gnu.org>
parents:
diff changeset
281 with one command; you can keep killing line after line, or word after
Dave Love <fx@gnu.org>
parents:
diff changeset
282 word, until you have killed it all, and you can still get it all back at
Dave Love <fx@gnu.org>
parents:
diff changeset
283 once.
Dave Love <fx@gnu.org>
parents:
diff changeset
284
Dave Love <fx@gnu.org>
parents:
diff changeset
285 Commands that kill forward from point add onto the end of the previous
Dave Love <fx@gnu.org>
parents:
diff changeset
286 killed text. Commands that kill backward from point add text onto the
Dave Love <fx@gnu.org>
parents:
diff changeset
287 beginning. This way, any sequence of mixed forward and backward kill
Dave Love <fx@gnu.org>
parents:
diff changeset
288 commands puts all the killed text into one entry without rearrangement.
Dave Love <fx@gnu.org>
parents:
diff changeset
289 Numeric arguments do not break the sequence of appending kills. For
Dave Love <fx@gnu.org>
parents:
diff changeset
290 example, suppose the buffer contains this text:
Dave Love <fx@gnu.org>
parents:
diff changeset
291
Dave Love <fx@gnu.org>
parents:
diff changeset
292 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
293 This is a line @point{}of sample text.
Dave Love <fx@gnu.org>
parents:
diff changeset
294 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
295
Dave Love <fx@gnu.org>
parents:
diff changeset
296 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
297 with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d
Dave Love <fx@gnu.org>
parents:
diff changeset
298 M-@key{DEL}}, killing alternately forward and backward, you end up with
Dave Love <fx@gnu.org>
parents:
diff changeset
299 @samp{a line of sample} as one entry in the kill ring, and @samp{This
Dave Love <fx@gnu.org>
parents:
diff changeset
300 is@ @ text.} in the buffer. (Note the double space, which you can clean
Dave Love <fx@gnu.org>
parents:
diff changeset
301 up with @kbd{M-@key{SPC}} or @kbd{M-q}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
302
Dave Love <fx@gnu.org>
parents:
diff changeset
303 Another way to kill the same text is to move back two words with
Dave Love <fx@gnu.org>
parents:
diff changeset
304 @kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}.
Dave Love <fx@gnu.org>
parents:
diff changeset
305 This produces exactly the same results in the buffer and in the kill
Dave Love <fx@gnu.org>
parents:
diff changeset
306 ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going
Dave Love <fx@gnu.org>
parents:
diff changeset
307 backward; once again, the result is the same. The text in the kill ring
Dave Love <fx@gnu.org>
parents:
diff changeset
308 entry always has the same order that it had in the buffer before you
Dave Love <fx@gnu.org>
parents:
diff changeset
309 killed it.
Dave Love <fx@gnu.org>
parents:
diff changeset
310
Dave Love <fx@gnu.org>
parents:
diff changeset
311 @kindex C-M-w
Dave Love <fx@gnu.org>
parents:
diff changeset
312 @findex append-next-kill
Dave Love <fx@gnu.org>
parents:
diff changeset
313 If a kill command is separated from the last kill command by other
Dave Love <fx@gnu.org>
parents:
diff changeset
314 commands (not just numeric arguments), it starts a new entry on the kill
Dave Love <fx@gnu.org>
parents:
diff changeset
315 ring. But you can force it to append by first typing the command
Dave Love <fx@gnu.org>
parents:
diff changeset
316 @kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w}
Dave Love <fx@gnu.org>
parents:
diff changeset
317 tells the following command, if it is a kill command, to append the text
Dave Love <fx@gnu.org>
parents:
diff changeset
318 it kills to the last killed text, instead of starting a new entry. With
Dave Love <fx@gnu.org>
parents:
diff changeset
319 @kbd{C-M-w}, you can kill several separated pieces of text and
Dave Love <fx@gnu.org>
parents:
diff changeset
320 accumulate them to be yanked back in one place.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
321
Dave Love <fx@gnu.org>
parents:
diff changeset
322 A kill command following @kbd{M-w} does not append to the text that
Dave Love <fx@gnu.org>
parents:
diff changeset
323 @kbd{M-w} copied into the kill ring.
Dave Love <fx@gnu.org>
parents:
diff changeset
324
Dave Love <fx@gnu.org>
parents:
diff changeset
325 @node Earlier Kills
Dave Love <fx@gnu.org>
parents:
diff changeset
326 @subsection Yanking Earlier Kills
Dave Love <fx@gnu.org>
parents:
diff changeset
327
Dave Love <fx@gnu.org>
parents:
diff changeset
328 @cindex yanking previous kills
Dave Love <fx@gnu.org>
parents:
diff changeset
329 @kindex M-y
Dave Love <fx@gnu.org>
parents:
diff changeset
330 @findex yank-pop
Dave Love <fx@gnu.org>
parents:
diff changeset
331 To recover killed text that is no longer the most recent kill, use the
Dave Love <fx@gnu.org>
parents:
diff changeset
332 @kbd{M-y} command (@code{yank-pop}). It takes the text previously
Dave Love <fx@gnu.org>
parents:
diff changeset
333 yanked and replaces it with the text from an earlier kill. So, to
Dave Love <fx@gnu.org>
parents:
diff changeset
334 recover the text of the next-to-the-last kill, first use @kbd{C-y} to
Dave Love <fx@gnu.org>
parents:
diff changeset
335 yank the last kill, and then use @kbd{M-y} to replace it with the
Dave Love <fx@gnu.org>
parents:
diff changeset
336 previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another
Dave Love <fx@gnu.org>
parents:
diff changeset
337 @kbd{M-y}.
Dave Love <fx@gnu.org>
parents:
diff changeset
338
Dave Love <fx@gnu.org>
parents:
diff changeset
339 You can understand @kbd{M-y} in terms of a ``last yank'' pointer which
Dave Love <fx@gnu.org>
parents:
diff changeset
340 points at an entry in the kill ring. Each time you kill, the ``last
Dave Love <fx@gnu.org>
parents:
diff changeset
341 yank'' pointer moves to the newly made entry at the front of the ring.
Dave Love <fx@gnu.org>
parents:
diff changeset
342 @kbd{C-y} yanks the entry which the ``last yank'' pointer points to.
Dave Love <fx@gnu.org>
parents:
diff changeset
343 @kbd{M-y} moves the ``last yank'' pointer to a different entry, and the
Dave Love <fx@gnu.org>
parents:
diff changeset
344 text in the buffer changes to match. Enough @kbd{M-y} commands can move
Dave Love <fx@gnu.org>
parents:
diff changeset
345 the pointer to any entry in the ring, so you can get any entry into the
Dave Love <fx@gnu.org>
parents:
diff changeset
346 buffer. Eventually the pointer reaches the end of the ring; the next
Dave Love <fx@gnu.org>
parents:
diff changeset
347 @kbd{M-y} moves it to the first entry again.
Dave Love <fx@gnu.org>
parents:
diff changeset
348
Dave Love <fx@gnu.org>
parents:
diff changeset
349 @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does
Dave Love <fx@gnu.org>
parents:
diff changeset
350 not change the order of the entries in the ring, which always runs from
Dave Love <fx@gnu.org>
parents:
diff changeset
351 the most recent kill at the front to the oldest one still remembered.
Dave Love <fx@gnu.org>
parents:
diff changeset
352
Dave Love <fx@gnu.org>
parents:
diff changeset
353 @kbd{M-y} can take a numeric argument, which tells it how many entries
Dave Love <fx@gnu.org>
parents:
diff changeset
354 to advance the ``last yank'' pointer by. A negative argument moves the
Dave Love <fx@gnu.org>
parents:
diff changeset
355 pointer toward the front of the ring; from the front of the ring, it
Dave Love <fx@gnu.org>
parents:
diff changeset
356 moves ``around'' to the last entry and continues forward from there.
Dave Love <fx@gnu.org>
parents:
diff changeset
357
Dave Love <fx@gnu.org>
parents:
diff changeset
358 Once the text you are looking for is brought into the buffer, you can
Dave Love <fx@gnu.org>
parents:
diff changeset
359 stop doing @kbd{M-y} commands and it will stay there. It's just a copy
Dave Love <fx@gnu.org>
parents:
diff changeset
360 of the kill ring entry, so editing it in the buffer does not change
Dave Love <fx@gnu.org>
parents:
diff changeset
361 what's in the ring. As long as no new killing is done, the ``last
Dave Love <fx@gnu.org>
parents:
diff changeset
362 yank'' pointer remains at the same place in the kill ring, so repeating
Dave Love <fx@gnu.org>
parents:
diff changeset
363 @kbd{C-y} will yank another copy of the same previous kill.
Dave Love <fx@gnu.org>
parents:
diff changeset
364
Dave Love <fx@gnu.org>
parents:
diff changeset
365 If you know how many @kbd{M-y} commands it would take to find the text
Dave Love <fx@gnu.org>
parents:
diff changeset
366 you want, you can yank that text in one step using @kbd{C-y} with a
Dave Love <fx@gnu.org>
parents:
diff changeset
367 numeric argument. @kbd{C-y} with an argument restores the text the
Dave Love <fx@gnu.org>
parents:
diff changeset
368 specified number of entries back in the kill ring. Thus, @kbd{C-u 2
Dave Love <fx@gnu.org>
parents:
diff changeset
369 C-y} gets the next-to-the-last block of killed text. It is equivalent
Dave Love <fx@gnu.org>
parents:
diff changeset
370 to @kbd{C-y M-y}. @kbd{C-y} with a numeric argument starts counting
Dave Love <fx@gnu.org>
parents:
diff changeset
371 from the ``last yank'' pointer, and sets the ``last yank'' pointer to
Dave Love <fx@gnu.org>
parents:
diff changeset
372 the entry that it yanks.
Dave Love <fx@gnu.org>
parents:
diff changeset
373
Dave Love <fx@gnu.org>
parents:
diff changeset
374 @vindex kill-ring-max
Dave Love <fx@gnu.org>
parents:
diff changeset
375 The length of the kill ring is controlled by the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
376 @code{kill-ring-max}; no more than that many blocks of killed text are
Dave Love <fx@gnu.org>
parents:
diff changeset
377 saved.
Dave Love <fx@gnu.org>
parents:
diff changeset
378
Dave Love <fx@gnu.org>
parents:
diff changeset
379 @vindex kill-ring
Dave Love <fx@gnu.org>
parents:
diff changeset
380 The actual contents of the kill ring are stored in a variable named
Dave Love <fx@gnu.org>
parents:
diff changeset
381 @code{kill-ring}; you can view the entire contents of the kill ring with
Dave Love <fx@gnu.org>
parents:
diff changeset
382 the command @kbd{C-h v kill-ring}.
Dave Love <fx@gnu.org>
parents:
diff changeset
383
Dave Love <fx@gnu.org>
parents:
diff changeset
384 @node Accumulating Text, Rectangles, Yanking, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
385 @section Accumulating Text
Dave Love <fx@gnu.org>
parents:
diff changeset
386 @findex append-to-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
387 @findex prepend-to-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
388 @findex copy-to-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
389 @findex append-to-file
Dave Love <fx@gnu.org>
parents:
diff changeset
390
Dave Love <fx@gnu.org>
parents:
diff changeset
391 @cindex accumulating scattered text
Dave Love <fx@gnu.org>
parents:
diff changeset
392 Usually we copy or move text by killing it and yanking it, but there
Dave Love <fx@gnu.org>
parents:
diff changeset
393 are other methods convenient for copying one block of text in many
Dave Love <fx@gnu.org>
parents:
diff changeset
394 places, or for copying many scattered blocks of text into one place. To
Dave Love <fx@gnu.org>
parents:
diff changeset
395 copy one block to many places, store it in a register
Dave Love <fx@gnu.org>
parents:
diff changeset
396 (@pxref{Registers}). Here we describe the commands to accumulate
Dave Love <fx@gnu.org>
parents:
diff changeset
397 scattered pieces of text into a buffer or into a file.
Dave Love <fx@gnu.org>
parents:
diff changeset
398
Dave Love <fx@gnu.org>
parents:
diff changeset
399 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
400 @item M-x append-to-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
401 Append region to contents of specified buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
402 @item M-x prepend-to-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
403 Prepend region to contents of specified buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
404 @item M-x copy-to-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
405 Copy region into specified buffer, deleting that buffer's old contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
406 @item M-x insert-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
407 Insert contents of specified buffer into current buffer at point.
Dave Love <fx@gnu.org>
parents:
diff changeset
408 @item M-x append-to-file
Dave Love <fx@gnu.org>
parents:
diff changeset
409 Append region to contents of specified file, at the end.
Dave Love <fx@gnu.org>
parents:
diff changeset
410 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
411
Dave Love <fx@gnu.org>
parents:
diff changeset
412 To accumulate text into a buffer, use @kbd{M-x append-to-buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
413 This reads a buffer name, then inserts a copy of the region into the
Dave Love <fx@gnu.org>
parents:
diff changeset
414 buffer specified. If you specify a nonexistent buffer,
Dave Love <fx@gnu.org>
parents:
diff changeset
415 @code{append-to-buffer} creates the buffer. The text is inserted
Dave Love <fx@gnu.org>
parents:
diff changeset
416 wherever point is in that buffer. If you have been using the buffer for
Dave Love <fx@gnu.org>
parents:
diff changeset
417 editing, the copied text goes into the middle of the text of the buffer,
Dave Love <fx@gnu.org>
parents:
diff changeset
418 wherever point happens to be in it.
Dave Love <fx@gnu.org>
parents:
diff changeset
419
Dave Love <fx@gnu.org>
parents:
diff changeset
420 Point in that buffer is left at the end of the copied text, so
Dave Love <fx@gnu.org>
parents:
diff changeset
421 successive uses of @code{append-to-buffer} accumulate the text in the
Dave Love <fx@gnu.org>
parents:
diff changeset
422 specified buffer in the same order as they were copied. Strictly
Dave Love <fx@gnu.org>
parents:
diff changeset
423 speaking, @code{append-to-buffer} does not always append to the text
Dave Love <fx@gnu.org>
parents:
diff changeset
424 already in the buffer---it appends only if point in that buffer is at the end.
Dave Love <fx@gnu.org>
parents:
diff changeset
425 However, if @code{append-to-buffer} is the only command you use to alter
Dave Love <fx@gnu.org>
parents:
diff changeset
426 a buffer, then point is always at the end.
Dave Love <fx@gnu.org>
parents:
diff changeset
427
Dave Love <fx@gnu.org>
parents:
diff changeset
428 @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer}
Dave Love <fx@gnu.org>
parents:
diff changeset
429 except that point in the other buffer is left before the copied text, so
Dave Love <fx@gnu.org>
parents:
diff changeset
430 successive prependings add text in reverse order. @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
431 copy-to-buffer} is similar except that any existing text in the other
Dave Love <fx@gnu.org>
parents:
diff changeset
432 buffer is deleted, so the buffer is left containing just the text newly
Dave Love <fx@gnu.org>
parents:
diff changeset
433 copied into it.
Dave Love <fx@gnu.org>
parents:
diff changeset
434
Dave Love <fx@gnu.org>
parents:
diff changeset
435 To retrieve the accumulated text from another buffer, use the command
Dave Love <fx@gnu.org>
parents:
diff changeset
436 @kbd{M-x insert-buffer}; this too takes @var{buffername} as an argument.
Dave Love <fx@gnu.org>
parents:
diff changeset
437 It inserts a copy of the text in buffer @var{buffername} into the
Dave Love <fx@gnu.org>
parents:
diff changeset
438 selected buffer. You can alternatively select the other buffer for
Dave Love <fx@gnu.org>
parents:
diff changeset
439 editing, then optionally move text from it by killing. @xref{Buffers},
Dave Love <fx@gnu.org>
parents:
diff changeset
440 for background information on buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
441
Dave Love <fx@gnu.org>
parents:
diff changeset
442 Instead of accumulating text within Emacs, in a buffer, you can append
Dave Love <fx@gnu.org>
parents:
diff changeset
443 text directly into a file with @kbd{M-x append-to-file}, which takes
Dave Love <fx@gnu.org>
parents:
diff changeset
444 @var{filename} as an argument. It adds the text of the region to the end
Dave Love <fx@gnu.org>
parents:
diff changeset
445 of the specified file. The file is changed immediately on disk.
Dave Love <fx@gnu.org>
parents:
diff changeset
446
Dave Love <fx@gnu.org>
parents:
diff changeset
447 You should use @code{append-to-file} only with files that are
Dave Love <fx@gnu.org>
parents:
diff changeset
448 @emph{not} being visited in Emacs. Using it on a file that you are
Dave Love <fx@gnu.org>
parents:
diff changeset
449 editing in Emacs would change the file behind Emacs's back, which
Dave Love <fx@gnu.org>
parents:
diff changeset
450 can lead to losing some of your editing.
Dave Love <fx@gnu.org>
parents:
diff changeset
451
Dave Love <fx@gnu.org>
parents:
diff changeset
452 @node Rectangles, Registers, Accumulating Text, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
453 @section Rectangles
Dave Love <fx@gnu.org>
parents:
diff changeset
454 @cindex rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
455 @cindex columns (and rectangles)
Dave Love <fx@gnu.org>
parents:
diff changeset
456 @cindex killing rectangular areas of text
Dave Love <fx@gnu.org>
parents:
diff changeset
457
Dave Love <fx@gnu.org>
parents:
diff changeset
458 The rectangle commands operate on rectangular areas of the text: all
Dave Love <fx@gnu.org>
parents:
diff changeset
459 the characters between a certain pair of columns, in a certain range of
Dave Love <fx@gnu.org>
parents:
diff changeset
460 lines. Commands are provided to kill rectangles, yank killed rectangles,
Dave Love <fx@gnu.org>
parents:
diff changeset
461 clear them out, fill them with blanks or text, or delete them. Rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
462 commands are useful with text in multicolumn formats, and for changing
Dave Love <fx@gnu.org>
parents:
diff changeset
463 text into or out of such formats.
Dave Love <fx@gnu.org>
parents:
diff changeset
464
Dave Love <fx@gnu.org>
parents:
diff changeset
465 When you must specify a rectangle for a command to work on, you do it
Dave Love <fx@gnu.org>
parents:
diff changeset
466 by putting the mark at one corner and point at the opposite corner. The
Dave Love <fx@gnu.org>
parents:
diff changeset
467 rectangle thus specified is called the @dfn{region-rectangle} because
Dave Love <fx@gnu.org>
parents:
diff changeset
468 you control it in about the same way the region is controlled. But
Dave Love <fx@gnu.org>
parents:
diff changeset
469 remember that a given combination of point and mark values can be
Dave Love <fx@gnu.org>
parents:
diff changeset
470 interpreted either as a region or as a rectangle, depending on the
Dave Love <fx@gnu.org>
parents:
diff changeset
471 command that uses them.
Dave Love <fx@gnu.org>
parents:
diff changeset
472
Dave Love <fx@gnu.org>
parents:
diff changeset
473 If point and the mark are in the same column, the rectangle they
Dave Love <fx@gnu.org>
parents:
diff changeset
474 delimit is empty. If they are in the same line, the rectangle is one
Dave Love <fx@gnu.org>
parents:
diff changeset
475 line high. This asymmetry between lines and columns comes about
Dave Love <fx@gnu.org>
parents:
diff changeset
476 because point (and likewise the mark) is between two columns, but within
Dave Love <fx@gnu.org>
parents:
diff changeset
477 a line.
Dave Love <fx@gnu.org>
parents:
diff changeset
478
Dave Love <fx@gnu.org>
parents:
diff changeset
479 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
480 @item C-x r k
Dave Love <fx@gnu.org>
parents:
diff changeset
481 Kill the text of the region-rectangle, saving its contents as the
Dave Love <fx@gnu.org>
parents:
diff changeset
482 ``last killed rectangle'' (@code{kill-rectangle}).
Dave Love <fx@gnu.org>
parents:
diff changeset
483 @item C-x r d
Dave Love <fx@gnu.org>
parents:
diff changeset
484 Delete the text of the region-rectangle (@code{delete-rectangle}).
Dave Love <fx@gnu.org>
parents:
diff changeset
485 @item C-x r y
Dave Love <fx@gnu.org>
parents:
diff changeset
486 Yank the last killed rectangle with its upper left corner at point
Dave Love <fx@gnu.org>
parents:
diff changeset
487 (@code{yank-rectangle}).
Dave Love <fx@gnu.org>
parents:
diff changeset
488 @item C-x r o
Dave Love <fx@gnu.org>
parents:
diff changeset
489 Insert blank space to fill the space of the region-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
490 (@code{open-rectangle}). This pushes the previous contents of the
Dave Love <fx@gnu.org>
parents:
diff changeset
491 region-rectangle rightward.
Dave Love <fx@gnu.org>
parents:
diff changeset
492 @item M-x clear-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
493 Clear the region-rectangle by replacing its contents with spaces.
Dave Love <fx@gnu.org>
parents:
diff changeset
494 @item M-x delete-whitespace-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
495 Delete whitespace in each of the lines on the specified rectangle,
Dave Love <fx@gnu.org>
parents:
diff changeset
496 starting from the left edge column of the rectangle.
27749
986871288b53 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 25829
diff changeset
497 @item C-x r t @var{string} @key{RET}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
498 Insert @var{string} on each line of the region-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
499 (@code{string-rectangle}).
Dave Love <fx@gnu.org>
parents:
diff changeset
500 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
501
Dave Love <fx@gnu.org>
parents:
diff changeset
502 The rectangle operations fall into two classes: commands deleting and
Dave Love <fx@gnu.org>
parents:
diff changeset
503 inserting rectangles, and commands for blank rectangles.
Dave Love <fx@gnu.org>
parents:
diff changeset
504
Dave Love <fx@gnu.org>
parents:
diff changeset
505 @kindex C-x r k
Dave Love <fx@gnu.org>
parents:
diff changeset
506 @kindex C-x r d
Dave Love <fx@gnu.org>
parents:
diff changeset
507 @findex kill-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
508 @findex delete-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
509 There are two ways to get rid of the text in a rectangle: you can
Dave Love <fx@gnu.org>
parents:
diff changeset
510 discard the text (delete it) or save it as the ``last killed''
Dave Love <fx@gnu.org>
parents:
diff changeset
511 rectangle. The commands for these two ways are @kbd{C-x r d}
Dave Love <fx@gnu.org>
parents:
diff changeset
512 (@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In
Dave Love <fx@gnu.org>
parents:
diff changeset
513 either case, the portion of each line that falls inside the rectangle's
Dave Love <fx@gnu.org>
parents:
diff changeset
514 boundaries is deleted, causing following text (if any) on the line to
Dave Love <fx@gnu.org>
parents:
diff changeset
515 move left into the gap.
Dave Love <fx@gnu.org>
parents:
diff changeset
516
Dave Love <fx@gnu.org>
parents:
diff changeset
517 Note that ``killing'' a rectangle is not killing in the usual sense; the
Dave Love <fx@gnu.org>
parents:
diff changeset
518 rectangle is not stored in the kill ring, but in a special place that
Dave Love <fx@gnu.org>
parents:
diff changeset
519 can only record the most recent rectangle killed. This is because yanking
Dave Love <fx@gnu.org>
parents:
diff changeset
520 a rectangle is so different from yanking linear text that different yank
Dave Love <fx@gnu.org>
parents:
diff changeset
521 commands have to be used and yank-popping is hard to make sense of.
Dave Love <fx@gnu.org>
parents:
diff changeset
522
Dave Love <fx@gnu.org>
parents:
diff changeset
523 @kindex C-x r y
Dave Love <fx@gnu.org>
parents:
diff changeset
524 @findex yank-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
525 To yank the last killed rectangle, type @kbd{C-x r y}
Dave Love <fx@gnu.org>
parents:
diff changeset
526 (@code{yank-rectangle}). Yanking a rectangle is the opposite of killing
Dave Love <fx@gnu.org>
parents:
diff changeset
527 one. Point specifies where to put the rectangle's upper left corner.
Dave Love <fx@gnu.org>
parents:
diff changeset
528 The rectangle's first line is inserted there, the rectangle's second
Dave Love <fx@gnu.org>
parents:
diff changeset
529 line is inserted at a position one line vertically down, and so on. The
Dave Love <fx@gnu.org>
parents:
diff changeset
530 number of lines affected is determined by the height of the saved
Dave Love <fx@gnu.org>
parents:
diff changeset
531 rectangle.
Dave Love <fx@gnu.org>
parents:
diff changeset
532
Dave Love <fx@gnu.org>
parents:
diff changeset
533 You can convert single-column lists into double-column lists using
Dave Love <fx@gnu.org>
parents:
diff changeset
534 rectangle killing and yanking; kill the second half of the list as a
Dave Love <fx@gnu.org>
parents:
diff changeset
535 rectangle and then yank it beside the first line of the list.
Dave Love <fx@gnu.org>
parents:
diff changeset
536 @xref{Two-Column}, for another way to edit multi-column text.
Dave Love <fx@gnu.org>
parents:
diff changeset
537
Dave Love <fx@gnu.org>
parents:
diff changeset
538 You can also copy rectangles into and out of registers with @kbd{C-x r
Dave Love <fx@gnu.org>
parents:
diff changeset
539 r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
540 Registers}.
Dave Love <fx@gnu.org>
parents:
diff changeset
541
Dave Love <fx@gnu.org>
parents:
diff changeset
542 @kindex C-x r o
Dave Love <fx@gnu.org>
parents:
diff changeset
543 @findex open-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
544 @findex clear-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
545 There are two commands you can use for making blank rectangles:
Dave Love <fx@gnu.org>
parents:
diff changeset
546 @kbd{M-x clear-rectangle} which blanks out existing text, and @kbd{C-x r
Dave Love <fx@gnu.org>
parents:
diff changeset
547 o} (@code{open-rectangle}) which inserts a blank rectangle. Clearing a
Dave Love <fx@gnu.org>
parents:
diff changeset
548 rectangle is equivalent to deleting it and then inserting a blank
Dave Love <fx@gnu.org>
parents:
diff changeset
549 rectangle of the same size.
Dave Love <fx@gnu.org>
parents:
diff changeset
550
Dave Love <fx@gnu.org>
parents:
diff changeset
551 @findex delete-whitespace-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
552 The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal
Dave Love <fx@gnu.org>
parents:
diff changeset
553 whitespace starting from a particular column. This applies to each of
Dave Love <fx@gnu.org>
parents:
diff changeset
554 the lines in the rectangle, and the column is specified by the left
Dave Love <fx@gnu.org>
parents:
diff changeset
555 edge of the rectangle. The right edge of the rectangle does not make
Dave Love <fx@gnu.org>
parents:
diff changeset
556 any difference to this command.
Dave Love <fx@gnu.org>
parents:
diff changeset
557
Dave Love <fx@gnu.org>
parents:
diff changeset
558 @kindex C-x r t
Dave Love <fx@gnu.org>
parents:
diff changeset
559 @findex string-rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
560 The command @kbd{C-x r t} (@code{M-x string-rectangle}) replaces the
Dave Love <fx@gnu.org>
parents:
diff changeset
561 rectangle with a specified string (inserted once on each line). The
Dave Love <fx@gnu.org>
parents:
diff changeset
562 string's width need not be the same as the width of the rectangle. If
Dave Love <fx@gnu.org>
parents:
diff changeset
563 the string's width is less, the text after the rectangle shifts left; if
Dave Love <fx@gnu.org>
parents:
diff changeset
564 the string is wider than the rectangle, the text after the rectangle
Dave Love <fx@gnu.org>
parents:
diff changeset
565 shifts right.
30895
2921bb6221db replace-rectangle
Dave Love <fx@gnu.org>
parents: 30865
diff changeset
566 @findex replace-rectangle
2921bb6221db replace-rectangle
Dave Love <fx@gnu.org>
parents: 30865
diff changeset
567 The command @kbd{M-x replace-rectangle} is similar, but replaces the
2921bb6221db replace-rectangle
Dave Love <fx@gnu.org>
parents: 30865
diff changeset
568 original version.