4.7. Holding Your Place with Bookmarks

Once you start working with multiple files, remembering just where you were in each one becomes harder. Bookmarks provide a convenient way of marking your place in a file, a place you can easily return to. You might, for example, be working with a file that has a long pathname. Rather than retype the pathname each time you start Emacs, you could just jump to a bookmark you've named current project by having Emacs find the file and put the cursor wherever you set the bookmark.

Bookmarks make the process of finding your place in any file easier. Particularly if you are working on a project several directories down from your home directory or in a totally different filesystem, putting bookmarks in the file makes it easy to get back there.

When you create a bookmark, Emacs creates a bookmark file in your home directory, called .emacs.bmk. It saves any new bookmarks in this file automatically when you exit Emacs.

Bookmarks are stored by user. If you and others access the same online documentation set, you can hold your place with your bookmark and they can hold their places with theirs, never interfering with each other's reading.

From the Edit menu, you can access the Bookmarks menu, which lists all the bookmark commands you'll probably ever need. We feel the menu interface for bookmarks is particularly well developed; even if you don't normally use menus, you might want to make an exception in this case. (At least until you learn the commands. Bookmarks are addictive, and when you use them frequently, the commands are easier to type than to reach by menu.)

4.7.1 Setting Bookmarks

To place a bookmark at the cursor position, type C-x r m (for bookmark-set). Emacs asks for a bookmark name, which can be virtually any length (practically speaking, as long as the width of your display) and can include spaces (so current project or Moore proposal's greatest flaw or Othello Act 2 Scene 4 would all be fine). Emacs also puts a default bookmark in parentheses, suggesting the filename if you haven't used a bookmark during this session (in which case it uses the bookmark name). Either press Enter to accept the default or type a bookmark name and then press Enter. You now have a bookmark you can jump to at any time, in any Emacs session.

One subtlety: if you give a new bookmark the same name as an old one, Emacs assumes you just want to move the bookmark, even if it was formerly in another file. So remember to make bookmark names unique unless you are really trying to move them.

4.7.2 Moving to a Bookmark

To move to a bookmark, press C-x r b (for bookmark-jump). Type the bookmark's name, or type the first few letters and press Tab. Emacs either finishes the bookmark's name or gives you a window of possible choices. Press Enter after the bookmark's name appears. Emacs retrieves the file and places the cursor at the bookmark location; the file is retrieved no matter how complicated its path is.

With menus, there's an easier way to move to a bookmark. When you select Edit Bookmarks Jump to Bookmark, Emacs displays a window of available bookmarks. Select the bookmark you want, and Emacs displays the file with the cursor in the bookmark's position. This is useful if you have set many bookmarks, but we prefer to stick with the keyboard as much as possible.

4.7.3 Renaming and Deleting Bookmarks

You may find that you made the name of your bookmark too generic; current project may be too vague if you are juggling projects and the one in your hand is the current one. To rename a bookmark, type M-x bookmark-rename. If you do the renaming from the keyboard, Emacs prompts Old bookmark name: and you type the old name and press Enter. (If you use the menus, you select the old name from a window instead.) Then Emacs asks, New name: and you type the new name and press Enter, all very straightforwardly. Renaming a bookmark does just that and nothing else: it doesn't change the bookmark's location or its contents; it simply changes its name.

To delete a bookmark, press M-x bookmark-delete. Type the name of the bookmark to delete or select it with the mouse. Deleting a bookmark doesn't in any way affect the file that was marked.

This discussion brings up an interesting question. What happens if you delete text in a file in which you've put a bookmark? Because a bookmark points to a position in a file and not to a piece of text, the bookmark stays in the same place after the text is deleted, just as the cursor remains in the same place after you delete several paragraphs. This fact is more intuitive than it sounds. You don't delete bookmarks by deleting marked text. Let's say you have a file with four lines. You bookmark the third line, then later delete lines two through four. When you jump to that bookmark again, it appears after the first line, the end of the file.

Inserting text works the same way. Bookmarks point to a position in a file, not to text. If you insert a new line before the third line, the bookmark remains at the point in the file where you set it, in this case, the beginning of the new line. If you move text around, the bookmark points to the same location in the file, the line and column where you set it.

What happens if you delete a file that has a bookmark in it? If you delete the whole file or even rename it and then try to access a bookmark attached to the file, Emacs gives you the following error message:

filename nonexistent. Relocate "bookmark name"? (y or n)

If you press y, you can give a new path to the file, which works well if you really just renamed or moved the file but didn't delete it. If you press n, however, Emacs gives you a message, along with some advice:

Bookmark not relocated, consider removing it

In other words, Emacs argues that no one needs bookmarks to nonexistent files, and we're inclined to agree.

4.7.4 Working with a List of Bookmarks

Remember the buffer list we discussed earlier in this chapter? Bookmarks have a similar list with one-letter commands that allow you to work with all your bookmarks at once.

To work with a list of bookmarks, type C-x r l (the lowercase letter "L"). The *Bookmark List* buffer appears.

Type: C-x r l

Emacs displays a list of bookmarks and the path to the associated files.

If you press Enter, f, or j, Emacs displays the bookmarked file with the cursor in the bookmarked location. From the bookmark list, press d to mark bookmarks for deletion, then x to delete them (unlike in the buffer list, in the bookmark list, deleting is the only reason you need the x command). If you change your mind, press Del to remove the d before you press x. Pressing r renames a bookmark, and Emacs prompts you for the new name. To save all the bookmarks, press s. You can mark several bookmarks and then display their associated files by typing m next to the bookmarks. A > appears beside bookmarks you've marked. When you've marked all you want, type v (for view) and Emacs pulls up the files associated with the bookmarks and displays them in multiple windows (with the cursor at the bookmarked location, of course). If you just want to move to one bookmarked file, you can press v without marking the bookmark first.

You can change the display of the bookmark list slightly by pressing t. By default, the list shows a bookmark's name, followed by the complete path to the file with which it is associated. If you press t (for toggle), only the bookmark names appear.

Table 4-5 summarizes the bookmark list commands. It includes a few commands relating to annotations; we'll cover these in the next section.

Table 4-5. Commands for editing the bookmark list

Command	Action
Enter, f, or j	Go to the bookmark on the current line.
C-o or o	Open the bookmark on the current line in another window; o moves the cursor to that window; C-o keeps the cursor in the current window.
d, C-d, or k	Flag bookmark for deletion.
r	Rename bookmark.
s	Save all bookmarks listed.
m	Mark bookmarks to be displayed in multiple windows.
v	Display marked bookmarks or the one the cursor is on if none are marked.
t	Toggle display of paths to files associated with bookmarks.
w	In the minibuffer, display location of file associated with bookmark.
x	Delete bookmarks flagged for deletion.
u	Remove mark from bookmark.
Del	Remove mark from bookmark on previous line or move to the previous line (if there is no mark).
q	Exit bookmark list.
Space or n	Move down a line.
p	Move up a line.
l	Load a bookmark file (other than the default).
A	Display all annotations.
a	Display annotation for current bookmark.
e	Edit (or create) annotation for the current bookmark.

4.7.5 Annotating Bookmarks

You can add annotations to your bookmarks. These annotations can provide any type of information you want: details about the file in question, what you are doing with it, documentation for someone else on your project to review when looking at your files, or really anything you want.

Annotations are most easily added from the bookmark list itself. Open the bookmark list using C-x r l, then move to the line of the bookmark you want to annotate. Type e, the command to edit an annotation.

From the bookmark list, type: e

Emacs opens a *Bookmark Annotation Compose* window.

Emacs provides some guidance in this buffer about what to do. It says that all lines that start with a comment mark (#) will be deleted and that you press C-c C-c to save and exit the annotations buffer.

The annotation includes lines that are commented out and won't become part of the annotation, but if you'd like to keep the Author and Date lines (logical portions of an annotation), just uncomment those lines by deleting the initial #. You then add any annotation you would like and press C-c C-c to exit the window.

Annotations exhibit a couple of behaviors that are at least annoying if not bugs. First, Emacs defines a # as the default fill prefix. You must either change that (see Chapter 6 for details) or delete the initial # if Emacs inserts it. Second, and more critically, Emacs doesn't automatically save annotations when you exit Emacs. If you set a bookmark, Emacs saves the bookmarks file automatically (and in fact without asking). If you set an annotation but do not add or move a bookmark during the session, you must save the bookmarks file manually by typing M-x bookmark-save.

After you add an annotation, Emacs puts an asterisk (*) before the bookmark name as a visual indication that the bookmark has been annotated. To display an annotation for the current bookmark, press a. To display all annotations, press A.

When you jump to a bookmark or move to a bookmarked file from the bookmark list, annotations are automatically displayed in another window (but don't edit them in this window; you must use the procedure described earlier). If you open the bookmarked file some other way (using C-x C-f, for example), annotations are not displayed.

4.7.6 A Few More Bookmark Commands

In addition to those we've discussed, there are a few more esoteric bookmark commands. These include bookmark-insert, which inserts the text of the bookmarked file at the cursor position; bookmark-write, which prompts for a new filename in which to save bookmarks; and bookmark-load, to load these separate bookmark files. These commands are less useful than the others, but you may think of some clever uses we have not.

Table 4-6 summarizes bookmark commands.

Table 4-6. Bookmark commands

Keystrokes	Command name	Action
C-x r mEdit Set Bookmark	bookmark-set	Set a bookmark at the current cursor position.
C-x r bEdit Jump to Bookmark	bookmark-jump	Jump to a bookmark.
(none)Edit Bookmarks bookmark-rename	Rename a bookmark.
(none)Edit Bookmarks bookmark-delete	Delete a bookmark.
(none)Edit Bookmarks bookmark-save	Save all bookmarks in default file.
C-x r lEdit Edit Bookmark List	bookmark-menu-list	Move to *Bookmark List* buffer.
(none)Edit Bookmarks bookmark-insert	Insert full text of file associated with a given bookmark.
(none)Edit Bookmarks bookmark-write	Save all bookmarks in a specified file.
(none)Edit Bookmarks bookmark-load	Load bookmarks from specified file.
(none)Edit Bookmarks bookmark-insert-location	Insert the path to a given bookmark at the cursor position.

Now that you know how to work with multiple buffers, frames, and windows, why not read the next chapter to discover some of the things you can do with them? Some, like using the directory editor and working with the command line from within Emacs, have been alluded to in this chapter.