(Fx_popup_menu): Add `else' to set Vmenu_updating_frame to nil
[emacs.git] / man / regs.texi
blob0992d75005289b3fca377036d71332f5fb855c04
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2002, 2003,
3 @c   2004, 2005 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Registers, Display, CUA Bindings, Top
6 @chapter Registers
7 @cindex registers
9   Emacs @dfn{registers} are compartments where you can save text,
10 rectangles, positions, and other things for later use.  Once you save
11 text or a rectangle in a register, you can copy it into the buffer
12 once, or many times; you can move point to a position saved in a
13 register once, or many times.
15 @findex view-register
16   Each register has a name, which consists of a single character.  A
17 register can store a number, a piece of text, a rectangle, a position,
18 a window configuration, or a file name, but only one thing at any
19 given time.  Whatever you store in a register remains there until you
20 store something else in that register.  To see what a register @var{r}
21 contains, use @kbd{M-x view-register}.
23 @table @kbd
24 @item M-x view-register @key{RET} @var{r}
25 Display a description of what register @var{r} contains.
26 @end table
28 @menu
29 * Position: RegPos.           Saving positions in registers.
30 * Text: RegText.              Saving text in registers.
31 * Rectangle: RegRect.         Saving rectangles in registers.
32 * Configurations: RegConfig.  Saving window configurations in registers.
33 * Numbers: RegNumbers.        Numbers in registers.
34 * Files: RegFiles.            File names in registers.
35 * Bookmarks::                 Bookmarks are like registers, but persistent.
36 @end menu
38 @node RegPos
39 @section Saving Positions in Registers
40 @cindex saving position in a register
42   Saving a position records a place in a buffer so that you can move
43 back there later.  Moving to a saved position switches to that buffer
44 and moves point to that place in it.
46 @table @kbd
47 @item C-x r @key{SPC} @var{r}
48 Save position of point in register @var{r} (@code{point-to-register}).
49 @item C-x r j @var{r}
50 Jump to the position saved in register @var{r} (@code{jump-to-register}).
51 @end table
53 @kindex C-x r SPC
54 @findex point-to-register
55   To save the current position of point in a register, choose a name
56 @var{r} and type @kbd{C-x r @key{SPC} @var{r}}.  The register @var{r}
57 retains the position thus saved until you store something else in that
58 register.
60 @kindex C-x r j
61 @findex jump-to-register
62   The command @kbd{C-x r j @var{r}} moves point to the position recorded
63 in register @var{r}.  The register is not affected; it continues to
64 hold the same position.  You can jump to the saved position any number
65 of times.
67   If you use @kbd{C-x r j} to go to a saved position, but the buffer it
68 was saved from has been killed, @kbd{C-x r j} tries to create the buffer
69 again by visiting the same file.  Of course, this works only for buffers
70 that were visiting files.
72 @node RegText
73 @section Saving Text in Registers
74 @cindex saving text in a register
76   When you want to insert a copy of the same piece of text several
77 times, it may be inconvenient to yank it from the kill ring, since each
78 subsequent kill moves that entry further down the ring.  An alternative
79 is to store the text in a register and later retrieve it.
81 @table @kbd
82 @item C-x r s @var{r}
83 Copy region into register @var{r} (@code{copy-to-register}).
84 @item C-x r i @var{r}
85 Insert text from register @var{r} (@code{insert-register}).
86 @item M-x append-to-register @key{RET} @var{r}
87 Append region to text in register @var{r}.
88 @item M-x prepend-to-register @key{RET} @var{r}
89 Prepend region to text in register @var{r}.
90 @end table
92 @kindex C-x r s
93 @kindex C-x r i
94 @findex copy-to-register
95 @findex insert-register
96   @kbd{C-x r s @var{r}} stores a copy of the text of the region into
97 the register named @var{r}.  @kbd{C-u C-x r s @var{r}}, the same
98 command with a numeric argument, deletes the text from the buffer as
99 well; you can think of this as ``moving'' the region text into the register.
101 @findex append-to-register
102 @findex prepend-to-register
103   @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
104 the text in the region to the text already stored in the register
105 named @var{r}.  If invoked with a numeric argument, it deletes the
106 region after appending it to the register.  The command
107 @code{prepend-to-register} is similar, except that it @emph{prepends}
108 the region text to the text in the register, rather than
109 @emph{appending} it.
111   @kbd{C-x r i @var{r}} inserts in the buffer the text from register
112 @var{r}.  Normally it leaves point before the text and places the mark
113 after, but with a numeric argument (@kbd{C-u}) it puts point after the
114 text and the mark before.
116 @node RegRect
117 @section Saving Rectangles in Registers
118 @cindex saving rectangle in a register
120   A register can contain a rectangle instead of linear text.  The
121 rectangle is represented as a list of strings.  @xref{Rectangles}, for
122 basic information on how to specify a rectangle in the buffer.
124 @table @kbd
125 @findex copy-rectangle-to-register
126 @kindex C-x r r
127 @item C-x r r @var{r}
128 Copy the region-rectangle into register @var{r}
129 (@code{copy-rectangle-to-register}).  With numeric argument, delete it as
130 well.
131 @item C-x r i @var{r}
132 Insert the rectangle stored in register @var{r} (if it contains a
133 rectangle) (@code{insert-register}).
134 @end table
136   The @kbd{C-x r i @var{r}} command inserts a text string if the
137 register contains one, and inserts a rectangle if the register contains
138 one.
140   See also the command @code{sort-columns}, which you can think of
141 as sorting a rectangle.  @xref{Sorting}.
143 @node RegConfig
144 @section Saving Window Configurations in Registers
145 @cindex saving window configuration in a register
147 @findex window-configuration-to-register
148 @findex frame-configuration-to-register
149 @kindex C-x r w
150 @kindex C-x r f
151   You can save the window configuration of the selected frame in a
152 register, or even the configuration of all windows in all frames, and
153 restore the configuration later.
155 @table @kbd
156 @item C-x r w @var{r}
157 Save the state of the selected frame's windows in register @var{r}
158 (@code{window-configuration-to-register}).
159 @item C-x r f @var{r}
160 Save the state of all frames, including all their windows, in register
161 @var{r} (@code{frame-configuration-to-register}).
162 @end table
164   Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
165 This is the same command used to restore a cursor position.  When you
166 restore a frame configuration, any existing frames not included in the
167 configuration become invisible.  If you wish to delete these frames
168 instead, use @kbd{C-u C-x r j @var{r}}.
170 @node RegNumbers
171 @section Keeping Numbers in Registers
172 @cindex saving number in a register
174   There are commands to store a number in a register, to insert
175 the number in the buffer in decimal, and to increment it.  These commands
176 can be useful in keyboard macros (@pxref{Keyboard Macros}).
178 @table @kbd
179 @item C-u @var{number} C-x r n @var{r}
180 @kindex C-x r n
181 @findex number-to-register
182 Store @var{number} into register @var{r} (@code{number-to-register}).
183 @item C-u @var{number} C-x r + @var{r}
184 @kindex C-x r +
185 @findex increment-register
186 Increment the number in register @var{r} by @var{number}
187 (@code{increment-register}).
188 @item C-x r i @var{r}
189 Insert the number from register @var{r} into the buffer.
190 @end table
192   @kbd{C-x r i} is the same command used to insert any other sort of
193 register contents into the buffer.  @kbd{C-x r +} with no numeric
194 argument increments the register value by 1; @kbd{C-x r n} with no
195 numeric argument stores zero in the register.
197 @node RegFiles
198 @section Keeping File Names in Registers
199 @cindex saving file name in a register
201   If you visit certain file names frequently, you can visit them more
202 conveniently if you put their names in registers.  Here's the Lisp code
203 used to put a file name in a register:
205 @smallexample
206 (set-register ?@var{r} '(file . @var{name}))
207 @end smallexample
209 @need 3000
210 @noindent
211 For example,
213 @smallexample
214 (set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
215 @end smallexample
217 @noindent
218 puts the file name shown in register @samp{z}.
220   To visit the file whose name is in register @var{r}, type @kbd{C-x r j
221 @var{r}}.  (This is the same command used to jump to a position or
222 restore a frame configuration.)
224 @node Bookmarks
225 @section Bookmarks
226 @cindex bookmarks
228   @dfn{Bookmarks} are somewhat like registers in that they record
229 positions you can jump to.  Unlike registers, they have long names, and
230 they persist automatically from one Emacs session to the next.  The
231 prototypical use of bookmarks is to record ``where you were reading'' in
232 various files.
234 @table @kbd
235 @item C-x r m @key{RET}
236 Set the bookmark for the visited file, at point.
238 @item C-x r m @var{bookmark} @key{RET}
239 @findex bookmark-set
240 Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
242 @item C-x r b @var{bookmark} @key{RET}
243 @findex bookmark-jump
244 Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
246 @item C-x r l
247 @findex list-bookmarks
248 List all bookmarks (@code{list-bookmarks}).
250 @item M-x bookmark-save
251 @findex bookmark-save
252 Save all the current bookmark values in the default bookmark file.
253 @end table
255 @kindex C-x r m
256 @findex bookmark-set
257 @kindex C-x r b
258 @findex bookmark-jump
259   The prototypical use for bookmarks is to record one current position
260 in each of several files.  So the command @kbd{C-x r m}, which sets a
261 bookmark, uses the visited file name as the default for the bookmark
262 name.  If you name each bookmark after the file it points to, then you
263 can conveniently revisit any of those files with @kbd{C-x r b}, and move
264 to the position of the bookmark at the same time.
266 @kindex C-x r l
267   To display a list of all your bookmarks in a separate buffer, type
268 @kbd{C-x r l} (@code{list-bookmarks}).  If you switch to that buffer,
269 you can use it to edit your bookmark definitions or annotate the
270 bookmarks.  Type @kbd{C-h m} in the bookmark buffer for more
271 information about its special editing commands.
273   When you kill Emacs, Emacs offers to save your bookmark values in your
274 default bookmark file, @file{~/.emacs.bmk}, if you have changed any
275 bookmark values.  You can also save the bookmarks at any time with the
276 @kbd{M-x bookmark-save} command.  The bookmark commands load your
277 default bookmark file automatically.  This saving and loading is how
278 bookmarks persist from one Emacs session to the next.
280 @vindex bookmark-save-flag
281   If you set the variable @code{bookmark-save-flag} to 1, then each
282 command that sets a bookmark will also save your bookmarks; this way,
283 you don't lose any bookmark values even if Emacs crashes.  (The value,
284 if a number, says how many bookmark modifications should go by between
285 saving.)
287 @vindex bookmark-search-size
288   Bookmark position values are saved with surrounding context, so that
289 @code{bookmark-jump} can find the proper position even if the file is
290 modified slightly.  The variable @code{bookmark-search-size} says how
291 many characters of context to record on each side of the bookmark's
292 position.
294   Here are some additional commands for working with bookmarks:
296 @table @kbd
297 @item M-x bookmark-load @key{RET} @var{filename} @key{RET}
298 @findex bookmark-load
299 Load a file named @var{filename} that contains a list of bookmark
300 values.  You can use this command, as well as @code{bookmark-write}, to
301 work with other files of bookmark values in addition to your default
302 bookmark file.
304 @item M-x bookmark-write @key{RET} @var{filename} @key{RET}
305 @findex bookmark-write
306 Save all the current bookmark values in the file @var{filename}.
308 @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
309 @findex bookmark-delete
310 Delete the bookmark named @var{bookmark}.
312 @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
313 @findex bookmark-insert-location
314 Insert in the buffer the name of the file that bookmark @var{bookmark}
315 points to.
317 @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
318 @findex bookmark-insert
319 Insert in the buffer the @emph{contents} of the file that bookmark
320 @var{bookmark} points to.
321 @end table
323 @ignore
324    arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64
325 @end ignore