2 @node Registers, Display, Rectangles, Top
6 XEmacs @dfn{registers} are places in which you can save text or
7 positions for later use. Once you save text or a rectangle in a
8 register, you can copy it into the buffer once or many times; a position
9 saved in a register is used by moving point to that position.
10 Rectangles can also be copied into and out of registers
14 Each register has a name which is a single character. A register can
15 store a piece of text, a rectangle, a position, a window configuration,
16 or a file name, but only one thing at any given time. Whatever you
17 store in a register remains there until you store something else in that
18 register. To see what a register @var{r} contains, use @kbd{M-x
22 @item M-x view-register @key{RET} @var{r}
23 Display a description of what register @var{r} contains.
27 @kbd{M-x view-register} reads a register name as an argument and then
28 displays the contents of the specified register.
31 * Position: RegPos. Saving positions in registers.
32 * Text: RegText. Saving text in registers.
33 * Rectangle: RegRect. Saving rectangles in registers.
34 * Configurations: RegConfig. Saving window configurations in registers.
35 * Files: RegFiles. File names in registers.
36 * Numbers: RegNumbers. Numbers in registers.
37 * Bookmarks:: Bookmarks are like registers, but persistent.
40 @node RegPos, RegText, Registers, Registers
41 @section Saving Positions in Registers
43 Saving a position records a place in a buffer so that you can move
44 back there later. Moving to a saved position switches to that buffer
45 and moves point to that place in it.
48 @item C-x r @key{SPC} @var{r}
49 Save position of point in register @var{r} (@code{point-to-register}).
51 Jump to the position saved in register @var{r} (@code{jump-to-register}).
55 @findex point-to-register
56 To save the current position of point in a register, choose a name
57 @var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r}
58 retains the position thus saved until you store something else in that
62 @findex jump-to-register
63 The command @kbd{C-x r j @var{r}} moves point to the position recorded
64 in register @var{r}. The register is not affected; it continues to
65 record the same location. You can jump to the same position using the
66 same register as often as you want.
68 If you use @kbd{C-x r j} to go to a saved position, but the buffer it
69 was saved from has been killed, @kbd{C-x r j} tries to create the buffer
70 again by visiting the same file. Of course, this works only for buffers
71 that were visiting files.
73 @node RegText, RegRect, RegPos, Registers
74 @section Saving Text in Registers
76 When you want to insert a copy of the same piece of text many times, it
77 can be impractical to use the kill ring, since each subsequent kill moves
78 the piece of text further down on the ring. It becomes hard to keep
79 track of the argument needed to retrieve the same text with @kbd{C-y}. An
80 alternative is to store the text in a register with @kbd{C-x r s}
81 (@code{copy-to-register}) and then retrieve it with @kbd{C-x r i}
82 (@code{insert-register}).
86 Copy region into register @var{r} (@code{copy-to-register}).
88 @itemx C-x r i @var{r}
89 Insert text contents of register @var{r} (@code{insert-register}).
95 @findex copy-to-register
96 @findex insert-register
97 @kbd{C-x r s @var{r}} stores a copy of the text of the region into the
98 register named @var{r}. Given a numeric argument, @kbd{C-x r s @var{r}}
99 deletes the text from the buffer as well.
101 @kbd{C-x r i @var{r}} inserts the text from register @var{r} in the buffer.
102 By default it leaves point before the text and places the mark after
103 it. With a numeric argument (@kbd{C-u}), it puts point after the text
104 and the mark before it.
106 @node RegRect, RegConfig, RegText, Registers
107 @section Saving Rectangles in Registers
110 A register can contain a rectangle instead of lines of text. The rectangle
111 is represented as a list of strings. @xref{Rectangles}, for basic
112 information on rectangles and how to specify rectangles in a buffer.
115 @findex copy-rectangle-to-register
117 @item C-x r r @var{r}
118 Copy the region-rectangle into register @var{r}
119 (@code{copy-rectangle-to-register}). With a numeric argument, delete it
121 @item C-x r g @var{r}
122 @itemx C-x r i @var{r}
123 Insert the rectangle stored in register @var{r} (if it contains a
124 rectangle) (@code{insert-register}).
127 The @kbd{C-x r i @var{r}} command inserts linear text if the register
129 that, or inserts a rectangle if the register contains one.
131 See also the command @code{sort-columns}, which you can think of
132 as sorting a rectangle. @xref{Sorting}.
134 @node RegConfig, RegNumbers, RegRect, Registers
135 @section Saving Window Configurations in Registers
137 @findex window-configuration-to-register
138 @findex frame-configuration-to-register
141 You can save the window configuration of the selected frame in a
142 register, or even the configuration of all windows in all frames, and
143 restore the configuration later.
146 @item C-x r w @var{r}
147 Save the state of the selected frame's windows in register @var{r}
148 (@code{window-configuration-to-register}).
149 @c @item C-x r f @var{r}
150 @item M-x frame-configuration-to-register @key{RET} @var{r}
151 Save the state of all frames, including all their windows, in register
152 @var{r} (@code{frame-configuration-to-register}).
155 Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
156 This is the same command used to restore a cursor position. When you
157 restore a frame configuration, any existing frames not included in the
158 configuration become invisible. If you wish to delete these frames
159 instead, use @kbd{C-u C-x r j @var{r}}.
161 @node RegNumbers, RegFiles, RegConfig, Registers
162 @section Keeping Numbers in Registers
164 There are commands to store a number in a register, to insert
165 the number in the buffer in decimal, and to increment it. These commands
166 can be useful in keyboard macros (@pxref{Keyboard Macros}).
169 @item C-u @var{number} C-x r n @var{reg}
171 @findex number-to-register
172 Store @var{number} into register @var{reg} (@code{number-to-register}).
173 @item C-u @var{number} C-x r + @var{reg}
175 @findex increment-register
176 Increment the number in register @var{reg} by @var{number}
177 (@code{increment-register}).
178 @item C-x r g @var{reg}
179 Insert the number from register @var{reg} into the buffer.
182 @kbd{C-x r g} is the same command used to insert any other
183 sort of register contents into the buffer.
185 @node RegFiles, Bookmarks, RegNumbers, Registers
186 @section Keeping File Names in Registers
188 If you visit certain file names frequently, you can visit them more
189 conveniently if you put their names in registers. Here's the Lisp code
190 used to put a file name in a register:
193 (set-register ?@var{r} '(file . @var{name}))
201 (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog"))
205 puts the file name shown in register @samp{z}.
207 To visit the file whose name is in register @var{r}, type @kbd{C-x r j
208 @var{r}}. (This is the same command used to jump to a position or
209 restore a frame configuration.)
211 @node Bookmarks, , RegFiles, Registers
215 @dfn{Bookmarks} are somewhat like registers in that they record
216 positions you can jump to. Unlike registers, they have long names, and
217 they persist automatically from one Emacs session to the next. The
218 prototypical use of bookmarks is to record ``where you were reading'' in
221 Note: bookmark.el is distributed in edit-utils package. You need to
222 install that to use bookmark facility (@pxref{Packages}).
225 @item C-x r m @key{RET}
226 Set the bookmark for the visited file, at point.
228 @item C-x r m @var{bookmark} @key{RET}
230 Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
232 @item C-x r b @var{bookmark} @key{RET}
233 @findex bookmark-jump
234 Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
237 @findex list-bookmarks
238 List all bookmarks (@code{list-bookmarks}).
240 @item M-x bookmark-save
241 @findex bookmark-save
242 Save all the current bookmark values in the default bookmark file.
248 @findex bookmark-jump
249 The prototypical use for bookmarks is to record one current position
250 in each of several files. So the command @kbd{C-x r m}, which sets a
251 bookmark, uses the visited file name as the default for the bookmark
252 name. If you name each bookmark after the file it points to, then you
253 can conveniently revisit any of those files with @kbd{C-x r b}, and move
254 to the position of the bookmark at the same time.
257 To display a list of all your bookmarks in a separate buffer, type
258 @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
259 you can use it to edit your bookmark definitions or annotate the
260 bookmarks. Type @kbd{C-h m} in that buffer for more information about
261 its special editing commands.
263 When you kill XEmacs, XEmacs offers to save your bookmark values in
264 your default bookmark file, @file{~/.emacs.bmk}, if you have changed any
265 bookmark values. You can also save the bookmarks at any time with the
266 @kbd{M-x bookmark-save} command. The bookmark commands load your
267 default bookmark file automatically. This saving and loading is how
268 bookmarks persist from one XEmacs session to the next.
270 @vindex bookmark-save-flag
271 If you set the variable @code{bookmark-save-flag} to 1, then each
272 command that sets a bookmark will also save your bookmarks; this way,
273 you don't lose any bookmark values even if XEmacs crashes. (The value,
274 if a number, says how many bookmark modifications should go by between
277 @vindex bookmark-search-size
278 Bookmark position values are saved with surrounding context, so that
279 @code{bookmark-jump} can find the proper position even if the file is
280 modified slightly. The variable @code{bookmark-search-size} says how
281 many characters of context to record, on each side of the bookmark's
284 Here are some additional commands for working with bookmarks:
287 @item M-x bookmark-load @key{RET} @var{filename} @key{RET}
288 @findex bookmark-load
289 Load a file named @var{filename} that contains a list of bookmark
290 values. You can use this command, as well as @code{bookmark-write}, to
291 work with other files of bookmark values in addition to your default
294 @item M-x bookmark-write @key{RET} @var{filename} @key{RET}
295 @findex bookmark-write
296 Save all the current bookmark values in the file @var{filename}.
298 @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
299 @findex bookmark-delete
300 Delete the bookmark named @var{bookmark}.
302 @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
303 @findex bookmark-insert-location
304 Insert in the buffer the name of the file that bookmark @var{bookmark}
307 @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
308 @findex bookmark-insert
309 Insert in the buffer the @emph{contents} of the file that bookmark
310 @var{bookmark} points to.