1 @node Registers, Display, Rectangles, Top
5 SXEmacs @dfn{registers} are places in which you can save text or
6 positions for later use. Once you save text or a rectangle in a
7 register, you can copy it into the buffer once or many times; a position
8 saved in a register is used by moving point to that position.
9 Rectangles can also be copied into and out of registers
13 Each register has a name which is a single character. A register can
14 store a piece of text, a rectangle, a position, a window configuration,
15 or a file name, but only one thing at any given time. Whatever you
16 store in a register remains there until you store something else in that
17 register. To see what a register @var{r} contains, use @kbd{M-x
21 @item M-x view-register @key{RET} @var{r}
22 Display a description of what register @var{r} contains.
26 @kbd{M-x view-register} reads a register name as an argument and then
27 displays the contents of the specified register.
30 * Position: RegPos. Saving positions in registers.
31 * Text: RegText. Saving text in registers.
32 * Rectangle: RegRect. Saving rectangles in registers.
33 * Configurations: RegConfig. Saving window configurations in registers.
34 * Files: RegFiles. File names in registers.
35 * Numbers: RegNumbers. Numbers in registers.
36 * Bookmarks:: Bookmarks are like registers, but persistent.
39 @node RegPos, RegText, Registers, Registers
40 @section Saving Positions in Registers
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.
47 @item C-x r @key{SPC} @var{r}
48 Save position of point in register @var{r} (@code{point-to-register}).
50 Jump to the position saved in register @var{r} (@code{jump-to-register}).
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
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 record the same location. You can jump to the same position using the
65 same register as often as you want.
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, RegRect, RegPos, Registers
73 @section Saving Text in Registers
75 When you want to insert a copy of the same piece of text many times, it
76 can be impractical to use the kill ring, since each subsequent kill moves
77 the piece of text further down on the ring. It becomes hard to keep
78 track of the argument needed to retrieve the same text with @kbd{C-y}. An
79 alternative is to store the text in a register with @kbd{C-x r s}
80 (@code{copy-to-register}) and then retrieve it with @kbd{C-x r i}
81 (@code{insert-register}).
85 Copy region into register @var{r} (@code{copy-to-register}).
87 @itemx C-x r i @var{r}
88 Insert text contents of register @var{r} (@code{insert-register}).
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 the
97 register named @var{r}. Given a numeric argument, @kbd{C-x r s @var{r}}
98 deletes the text from the buffer as well.
100 @kbd{C-x r i @var{r}} inserts the text from register @var{r} in the buffer.
101 By default it leaves point before the text and places the mark after
102 it. With a numeric argument (@kbd{C-u}), it puts point after the text
103 and the mark before it.
105 @node RegRect, RegConfig, RegText, Registers
106 @section Saving Rectangles in Registers
109 A register can contain a rectangle instead of lines of text. The rectangle
110 is represented as a list of strings. @xref{Rectangles}, for basic
111 information on rectangles and how to specify rectangles in a buffer.
114 @findex copy-rectangle-to-register
116 @item C-x r r @var{r}
117 Copy the region-rectangle into register @var{r}
118 (@code{copy-rectangle-to-register}). With a numeric argument, delete it
120 @item C-x r g @var{r}
121 @itemx C-x r i @var{r}
122 Insert the rectangle stored in register @var{r} (if it contains a
123 rectangle) (@code{insert-register}).
126 The @kbd{C-x r i @var{r}} command inserts linear text if the register
128 that, or inserts a rectangle if the register contains one.
130 See also the command @code{sort-columns}, which you can think of
131 as sorting a rectangle. @xref{Sorting}.
133 @node RegConfig, RegNumbers, RegRect, Registers
134 @section Saving Window Configurations in Registers
136 @findex window-configuration-to-register
137 @findex frame-configuration-to-register
140 You can save the window configuration of the selected frame in a
141 register, or even the configuration of all windows in all frames, and
142 restore the configuration later.
145 @item C-x r w @var{r}
146 Save the state of the selected frame's windows in register @var{r}
147 (@code{window-configuration-to-register}).
148 @c @item C-x r f @var{r}
149 @item M-x frame-configuration-to-register @key{RET} @var{r}
150 Save the state of all frames, including all their windows, in register
151 @var{r} (@code{frame-configuration-to-register}).
154 Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
155 This is the same command used to restore a cursor position. When you
156 restore a frame configuration, any existing frames not included in the
157 configuration become invisible. If you wish to delete these frames
158 instead, use @kbd{C-u C-x r j @var{r}}.
160 @node RegNumbers, RegFiles, RegConfig, Registers
161 @section Keeping Numbers in Registers
163 There are commands to store a number in a register, to insert
164 the number in the buffer in decimal, and to increment it. These commands
165 can be useful in keyboard macros (@pxref{Keyboard Macros}).
168 @item C-u @var{number} C-x r n @var{reg}
170 @findex number-to-register
171 Store @var{number} into register @var{reg} (@code{number-to-register}).
172 @item C-u @var{number} C-x r + @var{reg}
174 @findex increment-register
175 Increment the number in register @var{reg} by @var{number}
176 (@code{increment-register}).
177 @item C-x r g @var{reg}
178 Insert the number from register @var{reg} into the buffer.
181 @kbd{C-x r g} is the same command used to insert any other
182 sort of register contents into the buffer.
184 @node RegFiles, Bookmarks, RegNumbers, Registers
185 @section Keeping File Names in Registers
187 If you visit certain file names frequently, you can visit them more
188 conveniently if you put their names in registers. Here's the Lisp code
189 used to put a file name in a register:
192 (set-register ?@var{r} '(file . @var{name}))
200 (set-register ?z '(file . "/usr/src/sxemacs/src/ChangeLog"))
204 puts the file name shown in register @samp{z}.
206 To visit the file whose name is in register @var{r}, type @kbd{C-x r j
207 @var{r}}. (This is the same command used to jump to a position or
208 restore a frame configuration.)
210 @node Bookmarks, , RegFiles, Registers
214 @dfn{Bookmarks} are somewhat like registers in that they record
215 positions you can jump to. Unlike registers, they have long names, and
216 they persist automatically from one Emacs session to the next. The
217 prototypical use of bookmarks is to record ``where you were reading'' in
220 Note: bookmark.el is distributed in edit-utils package. You need to
221 install that to use bookmark facility (@pxref{Packages}).
224 @item C-x r m @key{RET}
225 Set the bookmark for the visited file, at point.
227 @item C-x r m @var{bookmark} @key{RET}
229 Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
231 @item C-x r b @var{bookmark} @key{RET}
232 @findex bookmark-jump
233 Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
236 @findex list-bookmarks
237 List all bookmarks (@code{list-bookmarks}).
239 @item M-x bookmark-save
240 @findex bookmark-save
241 Save all the current bookmark values in the default bookmark file.
247 @findex bookmark-jump
248 The prototypical use for bookmarks is to record one current position
249 in each of several files. So the command @kbd{C-x r m}, which sets a
250 bookmark, uses the visited file name as the default for the bookmark
251 name. If you name each bookmark after the file it points to, then you
252 can conveniently revisit any of those files with @kbd{C-x r b}, and move
253 to the position of the bookmark at the same time.
256 To display a list of all your bookmarks in a separate buffer, type
257 @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
258 you can use it to edit your bookmark definitions or annotate the
259 bookmarks. Type @kbd{C-h m} in that buffer for more information about
260 its special editing commands.
262 When you kill SXEmacs, SXEmacs offers to save your bookmark values in
263 your default bookmark file, @file{~/.emacs.bmk}, if you have changed any
264 bookmark values. You can also save the bookmarks at any time with the
265 @kbd{M-x bookmark-save} command. The bookmark commands load your
266 default bookmark file automatically. This saving and loading is how
267 bookmarks persist from one SXEmacs session to the next.
269 @vindex bookmark-save-flag
270 If you set the variable @code{bookmark-save-flag} to 1, then each
271 command that sets a bookmark will also save your bookmarks; this way,
272 you don't lose any bookmark values even if SXEmacs crashes. (The value,
273 if a number, says how many bookmark modifications should go by between
276 @vindex bookmark-search-size
277 Bookmark position values are saved with surrounding context, so that
278 @code{bookmark-jump} can find the proper position even if the file is
279 modified slightly. The variable @code{bookmark-search-size} says how
280 many characters of context to record, on each side of the bookmark's
283 Here are some additional commands for working with bookmarks:
286 @item M-x bookmark-load @key{RET} @var{filename} @key{RET}
287 @findex bookmark-load
288 Load a file named @var{filename} that contains a list of bookmark
289 values. You can use this command, as well as @code{bookmark-write}, to
290 work with other files of bookmark values in addition to your default
293 @item M-x bookmark-write @key{RET} @var{filename} @key{RET}
294 @findex bookmark-write
295 Save all the current bookmark values in the file @var{filename}.
297 @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
298 @findex bookmark-delete
299 Delete the bookmark named @var{bookmark}.
301 @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
302 @findex bookmark-insert-location
303 Insert in the buffer the name of the file that bookmark @var{bookmark}
306 @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
307 @findex bookmark-insert
308 Insert in the buffer the @emph{contents} of the file that bookmark
309 @var{bookmark} points to.