--- /dev/null
+
+@node Registers, Display, Rectangles, Top
+@chapter Registers
+@cindex registers
+
+ XEmacs @dfn{registers} are places in which you can save text or
+positions for later use. Once you save text or a rectangle in a
+register, you can copy it into the buffer once or many times; a position
+saved in a register is used by moving point to that position.
+Rectangles can also be copied into and out of registers
+(@pxref{Rectangles}).
+
+@findex view-register
+ Each register has a name which is a single character. A register can
+store 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}.
+
+@table @kbd
+@item M-x view-register @key{RET} @var{r}
+Display a description of what register @var{r} contains.
+@end table
+
+@findex view-register
+ @kbd{M-x view-register} reads a register name as an argument and then
+displays the contents of the specified register.
+
+@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.
+* Files: RegFiles. File names in registers.
+* Numbers: RegNumbers. Numbers in registers.
+* Bookmarks:: Bookmarks are like registers, but persistent.
+@end menu
+
+@node RegPos, RegText, Registers, Registers
+@section Saving Positions in Registers
+
+ 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}).
+@item C-x r j @var{r}
+Jump to the position 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.
+
+@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
+record the same location. You can jump to the same position using the
+same register as often as you want.
+
+ 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, RegRect, RegPos, Registers
+@section Saving Text in Registers
+
+ When you want to insert a copy of the same piece of text many times, it
+can be impractical to use the kill ring, since each subsequent kill moves
+the piece of text further down on the ring. It becomes hard to keep
+track of the argument needed to retrieve the same text with @kbd{C-y}. An
+alternative is to store the text in a register with @kbd{C-x r s}
+(@code{copy-to-register}) and then retrieve it with @kbd{C-x r i}
+(@code{insert-register}).
+
+@table @kbd
+@item C-x r s @var{r}
+Copy region into register @var{r} (@code{copy-to-register}).
+@item C-x r g @var{r}
+@itemx C-x r i @var{r}
+Insert text contents of register @var{r} (@code{insert-register}).
+@end table
+
+@kindex C-x r s
+@kindex C-x r g
+@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}. Given a numeric argument, @kbd{C-x r s @var{r}}
+deletes the text from the buffer as well.
+
+ @kbd{C-x r i @var{r}} inserts the text from register @var{r} in the buffer.
+By default it leaves point before the text and places the mark after
+it. With a numeric argument (@kbd{C-u}), it puts point after the text
+and the mark before it.
+
+@node RegRect, RegConfig, RegText, Registers
+@section Saving Rectangles in Registers
+@cindex rectangle
+
+ A register can contain a rectangle instead of lines of text. The rectangle
+is represented as a list of strings. @xref{Rectangles}, for basic
+information on rectangles and how to specify rectangles in a buffer.
+
+@table @kbd
+@findex copy-rectangle-to-register
+@kindex C-x r r
+@item C-x r r @var{r}
+Copy the region-rectangle into register @var{r}
+(@code{copy-rectangle-to-register}). With a numeric argument, delete it
+as well.
+@item C-x r g @var{r}
+@itemx C-x r i @var{r}
+Insert the rectangle stored in register @var{r} (if it contains a
+rectangle) (@code{insert-register}).
+@end table
+
+ The @kbd{C-x r i @var{r}} command inserts linear text if the register
+ contains
+that, or 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}.
+
+@node RegConfig, RegNumbers, RegRect, Registers
+@section Saving Window Configurations in Registers
+
+@findex window-configuration-to-register
+@findex frame-configuration-to-register
+@kindex C-x r w
+@c @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.
+
+@table @kbd
+@item C-x r w @var{r}
+Save the state of the selected frame's windows in register @var{r}
+(@code{window-configuration-to-register}).
+@c @item C-x r f @var{r}
+@item M-x frame-configuration-to-register @key{RET} @var{r}
+Save the state of all frames, including all their windows, in register
+@var{r} (@code{frame-configuration-to-register}).
+@end table
+
+ Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
+This is the same command used to restore a cursor position. When you
+restore a frame configuration, any existing frames not included in the
+configuration become invisible. If you wish to delete these frames
+instead, use @kbd{C-u C-x r j @var{r}}.
+
+@node RegNumbers, RegFiles, RegConfig, Registers
+@section Keeping Numbers in Registers
+
+ There are commands to store a number in a register, to insert
+the number in the buffer in decimal, and to increment it. These commands
+can be useful in keyboard macros (@pxref{Keyboard Macros}).
+
+@table @kbd
+@item C-u @var{number} C-x r n @var{reg}
+@kindex C-x r n
+@findex number-to-register
+Store @var{number} into register @var{reg} (@code{number-to-register}).
+@item C-u @var{number} C-x r + @var{reg}
+@kindex C-x r +
+@findex increment-register
+Increment the number in register @var{reg} by @var{number}
+(@code{increment-register}).
+@item C-x r g @var{reg}
+Insert the number from register @var{reg} into the buffer.
+@end table
+
+ @kbd{C-x r g} is the same command used to insert any other
+sort of register contents into the buffer.
+
+@node RegFiles, Bookmarks, RegNumbers, Registers
+@section Keeping File Names in Registers
+
+ 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:
+
+@smallexample
+(set-register ?@var{r} '(file . @var{name}))
+@end smallexample
+
+@need 3000
+@noindent
+For example,
+
+@smallexample
+(set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog"))
+@end smallexample
+
+@noindent
+puts the file name shown in register @samp{z}.
+
+ To visit the file whose name is 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 frame configuration.)
+
+@node Bookmarks, , RegFiles, Registers
+@section Bookmarks
+@cindex bookmarks
+
+ @dfn{Bookmarks} are somewhat like registers in that they record
+positions you can jump to. Unlike registers, they have long names, and
+they persist automatically from one Emacs session to the next. The
+prototypical use of bookmarks is to record ``where you were reading'' in
+various files.
+
+ Note: bookmark.el is distributed in edit-utils package. You need to
+install that to use bookmark facility (@pxref{Packages}).
+
+@table @kbd
+@item C-x r m @key{RET}
+Set the bookmark for the visited file, at point.
+
+@item C-x r m @var{bookmark} @key{RET}
+@findex bookmark-set
+Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
+
+@item C-x r b @var{bookmark} @key{RET}
+@findex bookmark-jump
+Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
+
+@item C-x r l
+@findex list-bookmarks
+List all bookmarks (@code{list-bookmarks}).
+
+@item M-x bookmark-save
+@findex bookmark-save
+Save all the current bookmark values in the default bookmark file.
+@end table
+
+@kindex C-x r m
+@findex bookmark-set
+@kindex C-x r b
+@findex bookmark-jump
+ The prototypical use for bookmarks is to record one current position
+in each of several files. So the command @kbd{C-x r m}, which sets a
+bookmark, uses the visited file name as the default for the bookmark
+name. If you name each bookmark after the file it points to, then you
+can conveniently revisit any of those files with @kbd{C-x r b}, and move
+to the position of the bookmark at the same time.
+
+@kindex C-x r l
+ To display a list of all your bookmarks in a separate buffer, type
+@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
+you can use it to edit your bookmark definitions or annotate the
+bookmarks. Type @kbd{C-h m} in that buffer for more information about
+its special editing commands.
+
+ When you kill XEmacs, XEmacs 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 XEmacs 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 XEmacs crashes. (The value,
+if a number, says how many bookmark modifications should go by between
+saving.)
+
+@vindex bookmark-search-size
+ Bookmark position values are saved with surrounding context, so that
+@code{bookmark-jump} can find the proper position even if the file is
+modified slightly. The variable @code{bookmark-search-size} says how
+many characters of context to record, on each side of the bookmark's
+position.
+
+ Here are some additional commands for working with bookmarks:
+
+@table @kbd
+@item M-x bookmark-load @key{RET} @var{filename} @key{RET}
+@findex bookmark-load
+Load a file named @var{filename} that contains a list of bookmark
+values. You can use this command, as well as @code{bookmark-write}, to
+work with other files of bookmark values in addition to your default
+bookmark file.
+
+@item M-x bookmark-write @key{RET} @var{filename} @key{RET}
+@findex bookmark-write
+Save all the current bookmark values in the file @var{filename}.
+
+@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
+@findex bookmark-delete
+Delete the bookmark named @var{bookmark}.
+
+@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
+@findex bookmark-insert-location
+Insert in the buffer the name of the file that bookmark @var{bookmark}
+points to.
+
+@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
+@findex bookmark-insert
+Insert in the buffer the @emph{contents} of the file that bookmark
+@var{bookmark} points to.
+@end table
projects / chise / xemacs-chise.git / blobdiff