@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Registers, Display, CUA Bindings, Top
+@node Registers
@chapter Registers
@cindex registers
Emacs @dfn{registers} are compartments where you can save text,
rectangles, positions, and other things for later use. Once you save
text or a rectangle in a register, you can copy it into the buffer
-once, or many times; you can move point to a position saved in a
-register once, or many times.
+once, or many times; once you save a position in a register, you can
+jump back to that position once, or many times.
+
+ Each register has a name that consists of a single character, which
+we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
+or a number (such as @samp{1}); case matters, so register @samp{a} is
+not the same as register @samp{A}.
@findex view-register
- Each register has a name, which consists of a single character. A
-register can store a number, a piece of text, a rectangle, a position,
-a window configuration, or a file name, but only one thing at any
-given time. Whatever you store in a register remains there until you
-store something else in that register. To see what a register @var{r}
-contains, use @kbd{M-x view-register}.
+ A register can store a position, a piece of text, a rectangle, a
+number, a window configuration, or a file name, but only one thing at
+any given time. Whatever you store in a register remains there until
+you store something else in that register. To see what register
+@var{r} contains, use @kbd{M-x view-register}:
@table @kbd
@item M-x view-register @key{RET} @var{r}
Display a description of what register @var{r} contains.
@end table
+@vindex register-preview-delay
+@cindex preview of registers
+ All of the commands that prompt for a register will display a
+``preview'' window that lists the existing registers (if there are
+any) after a short delay. To change the length of the delay,
+customize @code{register-preview-delay}. To prevent this display, set
+that option to @code{nil}. You can explicitly request a preview
+window by pressing @kbd{C-h} or @key{F1}.
+
@dfn{Bookmarks} record files and positions in them, so you can
-return to those positions when you look at the file again.
-Bookmarks are similar enough in spirit to registers that they
-seem to belong in this chapter.
+return to those positions when you look at the file again. Bookmarks
+are similar in spirit to registers, so they are also documented in
+this chapter.
@menu
-* Position: RegPos. Saving positions in registers.
-* Text: RegText. Saving text in registers.
-* Rectangle: RegRect. Saving rectangles in registers.
-* Configurations: RegConfig. Saving window configurations in registers.
-* Numbers: RegNumbers. Numbers in registers.
-* Files: RegFiles. File names in registers.
-* Bookmarks:: Bookmarks are like registers, but persistent.
+* Position Registers:: Saving positions in registers.
+* Text Registers:: Saving text in registers.
+* Rectangle Registers:: Saving rectangles in registers.
+* Configuration Registers:: Saving window configurations in registers.
+* Number Registers:: Numbers in registers.
+* File Registers:: File names in registers.
+* Keyboard Macro Registers:: Keyboard macros in registers.
+* Bookmarks:: Bookmarks are like registers, but persistent.
@end menu
-@node RegPos
+@node Position Registers
@section Saving Positions in Registers
@cindex saving position in a register
- Saving a position records a place in a buffer so that you can move
-back there later. Moving to a saved position switches to that buffer
-and moves point to that place in it.
-
@table @kbd
@item C-x r @key{SPC} @var{r}
-Save position of point in register @var{r} (@code{point-to-register}).
+Record the position of point and the current buffer in register
+@var{r} (@code{point-to-register}).
@item C-x r j @var{r}
-Jump to the position saved in register @var{r} (@code{jump-to-register}).
+Jump to the position and buffer saved in register @var{r}
+(@code{jump-to-register}).
@end table
@kindex C-x r SPC
@findex point-to-register
- To save the current position of point in a register, choose a name
-@var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r}
-retains the position thus saved until you store something else in that
-register.
+ Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by
+a character @kbd{@var{r}}, saves both the position of point and the
+current buffer in register @var{r}. The register retains this
+information until you store something else in it.
@kindex C-x r j
@findex jump-to-register
- The command @kbd{C-x r j @var{r}} moves point to the position recorded
-in register @var{r}. The register is not affected; it continues to
-hold the same position. You can jump to the saved position any number
-of times.
+ The command @kbd{C-x r j @var{r}} switches to the buffer recorded in
+register @var{r}, and moves point to the recorded position. The
+contents of the register are not changed, so you can jump to the saved
+position any number of times.
If you use @kbd{C-x r j} to go to a saved position, but the buffer it
was saved from has been killed, @kbd{C-x r j} tries to create the buffer
again by visiting the same file. Of course, this works only for buffers
that were visiting files.
-@node RegText
+@node Text Registers
@section Saving Text in Registers
@cindex saving text in a register
Insert text from register @var{r} (@code{insert-register}).
@item M-x append-to-register @key{RET} @var{r}
Append region to text in register @var{r}.
+
+@kindex C-x r +
+When register @var{r} contains text, you can use @kbd{C-x r +}
+(@code{increment-register}) to append to that register. Note that
+command @kbd{C-x r +} behaves differently if @var{r} contains a
+number. @xref{Number Registers}.
+
@item M-x prepend-to-register @key{RET} @var{r}
Prepend region to text in register @var{r}.
@end table
@kindex C-x r s
-@kindex C-x r i
@findex copy-to-register
-@findex insert-register
@kbd{C-x r s @var{r}} stores a copy of the text of the region into
-the register named @var{r}. @kbd{C-u C-x r s @var{r}}, the same
-command with a numeric argument, deletes the text from the buffer as
-well; you can think of this as ``moving'' the region text into the register.
+the register named @var{r}. If the mark is inactive, Emacs first
+reactivates the mark where it was last set. The mark is deactivated
+at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}},
+the same command with a prefix argument, copies the text into register
+@var{r} and deletes the text from the buffer as well; you can think of
+this as ``moving'' the region text into the register.
@findex append-to-register
@findex prepend-to-register
@kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
the text in the region to the text already stored in the register
-named @var{r}. If invoked with a numeric argument, it deletes the
+named @var{r}. If invoked with a prefix argument, it deletes the
region after appending it to the register. The command
@code{prepend-to-register} is similar, except that it @emph{prepends}
-the region text to the text in the register, rather than
+the region text to the text in the register instead of
@emph{appending} it.
+@vindex register-separator
+ When you are collecting text using @code{append-to-register} and
+@code{prepend-to-register}, you may want to separate individual
+collected pieces using a separator. In that case, configure a
+@code{register-separator} and store the separator text in to that
+register. For example, to get double newlines as text separator
+during the collection process, you can use the following setting.
+
+@example
+(setq register-separator ?+)
+(set-register register-separator "\n\n")
+@end example
+
+@kindex C-x r i
+@findex insert-register
@kbd{C-x r i @var{r}} inserts in the buffer the text from register
-@var{r}. Normally it leaves point before the text and places the mark
-after, but with a numeric argument (@kbd{C-u}) it puts point after the
-text and the mark before.
+@var{r}. Normally it leaves point after the text and sets the mark
+before, without activating it. With a numeric argument, it instead
+puts before after the text and the mark after.
-@node RegRect
+@node Rectangle Registers
@section Saving Rectangles in Registers
@cindex saving rectangle in a register
- A register can contain a rectangle instead of linear text. The
-rectangle is represented as a list of strings. @xref{Rectangles}, for
-basic information on how to specify a rectangle in the buffer.
+ A register can contain a rectangle instead of linear text.
+@xref{Rectangles}, for basic information on how to specify a rectangle
+in the buffer.
@table @kbd
@findex copy-rectangle-to-register
rectangle) (@code{insert-register}).
@end table
- The @kbd{C-x r i @var{r}} command inserts a text string if the
-register contains one, and inserts a rectangle if the register contains
-one.
-
- See also the command @code{sort-columns}, which you can think of
-as sorting a rectangle. @xref{Sorting}.
+ The @kbd{C-x r i @var{r}} (@code{insert-register}) command,
+previously documented in @ref{Text Registers}, inserts a rectangle
+rather than a text string, if the register contains a rectangle.
-@node RegConfig
+@node Configuration Registers
@section Saving Window Configurations in Registers
@cindex saving window configuration in a register
@findex window-configuration-to-register
-@findex frame-configuration-to-register
+@findex frameset-to-register
@kindex C-x r w
@kindex C-x r f
You can save the window configuration of the selected frame in a
register, or even the configuration of all windows in all frames, and
-restore the configuration later.
+restore the configuration later. @xref{Windows}, for information
+about window configurations.
@table @kbd
@item C-x r w @var{r}
(@code{window-configuration-to-register}).
@item C-x r f @var{r}
Save the state of all frames, including all their windows, in register
-@var{r} (@code{frame-configuration-to-register}).
+@var{r} (@code{frameset-to-register}).
@end table
Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
configuration become invisible. If you wish to delete these frames
instead, use @kbd{C-u C-x r j @var{r}}.
-@node RegNumbers
+@node Number Registers
@section Keeping Numbers in Registers
@cindex saving number in a register
@item C-u @var{number} C-x r + @var{r}
@kindex C-x r +
@findex increment-register
-Increment the number in register @var{r} by @var{number}
-(@code{increment-register}).
+If @var{r} contains a number, increment the number in that register by
+@var{number}. Note that command @kbd{C-x r +}
+(@code{increment-register}) behaves differently if @var{r} contains
+text. @xref{Text Registers}.
@item C-x r i @var{r}
Insert the number from register @var{r} into the buffer.
@end table
argument increments the register value by 1; @kbd{C-x r n} with no
numeric argument stores zero in the register.
-@node RegFiles
+@node File Registers
@section Keeping File Names in Registers
@cindex saving file name in a register
If you visit certain file names frequently, you can visit them more
conveniently if you put their names in registers. Here's the Lisp code
-used to put a file name in a register:
+used to put a file @var{name} into register @var{r}:
@smallexample
-(set-register ?@var{r} '(file . @var{name}))
+(set-register @var{r} '(file . @var{name}))
@end smallexample
@need 3000
@var{r}}. (This is the same command used to jump to a position or
restore a frame configuration.)
+@node Keyboard Macro Registers
+@section Keyboard Macro Registers
+@cindex saving keyboard macro in a register
+@cindex keyboard macros, in registers
+
+@kindex C-x C-k x
+@findex kmacro-to-register
+ If you need to execute a keyboard macro (@pxref{Keyboard Macros})
+frequently, it is more convenient to put it in a register or save it
+(@pxref{Save Keyboard Macro}). @kbd{C-x C-k x @var{r}}
+(@code{kmacro-to-register}) stores the last keyboard macro in register
+@var{r}.
+
+ To execute the keyboard macro in register @var{r}, type @kbd{C-x r j
+@var{r}}. (This is the same command used to jump to a position or
+restore a frameset.)
+
@node Bookmarks
@section Bookmarks
@cindex bookmarks
bookmarks. Type @kbd{C-h m} in the bookmark buffer for more
information about its special editing commands.
- When you kill Emacs, Emacs offers to save your bookmark values in your
-default bookmark file, @file{~/.emacs.bmk}, if you have changed any
-bookmark values. You can also save the bookmarks at any time with the
-@kbd{M-x bookmark-save} command. The bookmark commands load your
-default bookmark file automatically. This saving and loading is how
-bookmarks persist from one Emacs session to the next.
+ When you kill Emacs, Emacs saves your bookmarks, if
+you have changed any bookmark values. You can also save the bookmarks
+at any time with the @kbd{M-x bookmark-save} command. Bookmarks are
+saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with
+older versions of Emacs, if you have a file named @file{~/.emacs.bmk},
+that is used instead). The bookmark commands load your default
+bookmark file automatically. This saving and loading is how bookmarks
+persist from one Emacs session to the next.
@vindex bookmark-save-flag
- If you set the variable @code{bookmark-save-flag} to 1, then each
-command that sets a bookmark will also save your bookmarks; this way,
-you don't lose any bookmark values even if Emacs crashes. (The value,
-if a number, says how many bookmark modifications should go by between
-saving.)
+ If you set the variable @code{bookmark-save-flag} to 1, each command
+that sets a bookmark will also save your bookmarks; this way, you
+don't lose any bookmark values even if Emacs crashes. The value, if
+a number, says how many bookmark modifications should go by between
+saving. If you set this variable to @code{nil}, Emacs only
+saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.
+
+@vindex bookmark-default-file
+ The variable @code{bookmark-default-file} specifies the file in
+which to save bookmarks by default.
@vindex bookmark-search-size
Bookmark position values are saved with surrounding context, so that
Insert in the buffer the @emph{contents} of the file that bookmark
@var{bookmark} points to.
@end table
-
-@ignore
- arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64
-@end ignore