EmacsWiki: Bookmark Plus (original) (raw)

This page is about package Bookmark+, which enhances vanilla Emacs bookmarks in many ways. For background about Emacs bookmarks, see the following:

With Bookmark+ you can use bookmarks that were created with any Emacs version in any other Emacs version. But see also Compatibility, below.

To report Bookmark+ bugs: Use ‘M-x customize-group bookmark-plus’. Then follow (e.g. click) the link Send Bug Report, which helps you prepare an email to me.

Quick Start

Some basic keys you can use anywhere:

Some keys you can use in your bookmarks list (from ‘C-x r l’):

Some keys you can use in DiredMode:

Bookmark+ Libraries

Bookmark+ is composed of these libraries:

The main Bookmark+ library is bookmark+.el. The other required libraries are bookmark+-mac.el, bookmark+-bmu.el, bookmark+-1.el, and bookmark+-key.el. If you want to be able to highlight bookmarks then you will also need library bookmark+-lit.el. I recommend that you byte-compile all of the libraries, after loading the source files (in particular, load bookmark+-mac.el).

Put the directory of these libraries in your ‘load-path’ and add this to your init file:

(require 'bookmark+)

That will load all of the Bookmark+ libraries. If you do not care about bookmark highlighting then simply do not put bookmark+-lit.el in your ‘load-path’.

By default (see option ‘bmkp-crosshairs-flag’), when you visit a bookmark that has no region it is highlighted temporarily using crosshairs, for easy recognition. (This temporary highlighting is independent of the highlighting provided by bookmark+-lit.el.)

For this optional crosshairs feature you also need library crosshairs.el, which in turn requires libraries col-highlight.el, hl-line, hl-line+.el, and vline.el. Library hl-line comes with vanilla Emacs. You also need Emacs 22 or later for this feature.

Where to Obtain Bookmark+ Files

UPDATE, 2021-04:

(See also the update below, from 2017-10.)

A user informs me that there are these additional ways to install and update Bookmark+ automatically, using Quelpa, which lets you download and build packages from various sources, including EmacsWiki.

(quelpa '(bookmark+ :fetcher wiki
                    :files
                    ("bookmark+.el"
                     "bookmark+-mac.el"
                     "bookmark+-bmu.el"
                     "bookmark+-1.el"
                     "bookmark+-key.el"
                     "bookmark+-lit.el"
                     "bookmark+-doc.el"
                     "bookmark+-chg.el")))

And Quelpa can be combined with library ‘use-package’, as follows:

(use-package bookmark+
             :quelpa (bookmark+ :fetcher wiki
                                :files
                                ("bookmark+.el"
                                 "bookmark+-mac.el"
                                 "bookmark+-bmu.el"
                                 "bookmark+-1.el"
                                 "bookmark+-key.el"
                                 "bookmark+-lit.el"
                                 "bookmark+-doc.el"
                                 "bookmark+-chg.el"))
             :defer 2)

2024-09-11 - it is also possible to do:

(use-package bookmark+ :ensure t :straight t)

if you have straight installed

As always, you should read the Commentary in (at least) file bookmark+.el. In particular, read the NOTE there about updating Bookmark+. And in particular:

Always load bookmark+-mac.el (not bookmark+-mac.elc) before you byte-compile new versions of the files, in case there have been any changes to Lisp macros (in bookmark+-mac.el).

That NOTE is repeated in the Commentary of some of the individual Lisp files, in particular bookmark+-chg.el.

UPDATE, 2017-10:

Bookmark+, as well as my other libraries that are on EmacsWiki, used to be obtainable also from MELPA. You may still find some of them there, but they are likely not up-to-date.

MELPA has decided to no longer accept Lisp libraries from EmacsWiki. This includes my libraries, even though these libraries are read-only (administrator lock on the wiki pages). Too bad. This means that you must download Bookmark+ and my other libraries only from Emacs Wiki. Sorry about that. I upload Bookmark+ files only to the wiki.

JonasBernoulli ‘s GitHub mirror for Bookmark+ is also apparently not being updated, or at least not frequently.

The following information is therefore out-of-date, though you might still be able to get an old version of Bookmark+ these ways.

Besides the EmacsWiki ElispArea, which always has the latest source files for Bookmark+ you can the get Bookmark+ files in the following ways:

From tetris11:

If you wish to load the latest Bookmark+ from the EmacsWiki, then you can add the following to your startup elisp, which will download and byte-compile all files for you, and load the library.

    (let ((bookmarkplus-dir "~/.emacs.d/custom/bookmark-plus/")
          (emacswiki-base "https://www.emacswiki.org/emacs/download/")
          (bookmark-files '("bookmark+.el" "bookmark+-mac.el" "bookmark+-bmu.el" "bookmark+-key.el" "bookmark+-lit.el" "bookmark+-1.el")))
      (require 'url)
      (add-to-list 'load-path bookmarkplus-dir)
      (make-directory bookmarkplus-dir t)
      (mapcar (lambda (arg)
                (let ((local-file (concat bookmarkplus-dir arg)))
                  (unless (file-exists-p local-file)
                    (url-copy-file (concat emacswiki-base arg) local-file t))))
                bookmark-files)
      (byte-recompile-directory bookmarkplus-dir 0)
      (require 'bookmark+))

– tetris11

Please, after you download all of the Bookmark+ files, first load bookmark+-mac.el, before you byte-compile and load all of the files. It contains the latest Lisp macros needed for proper byte-compiling.

Thx - DrewAdams

Bookmark+ Load Order and Option `bookmark-default-file'

Standard option ‘bookmark-default-file’ defines the default location of your bookmark file. Bookmark+ does not change the value. You can change the value, of course, either by customizing it (recommended) or using Lisp code (including in your init file).

However, the value of ‘bookmark-default-file’ is used when you load Bookmark+ to initialize some other variables, in particular option ‘bmkp-last-as-first-bookmark-file’ and internal variable ‘bmkp-current-bookmark-file’.

This means that if you modify ‘bookmark-default-file’ in your init file, and you want your new value to be take into account by Bookmark+, then modify it before you load Bookmark+.

Be aware also that another library that you load might, itself, load Bookmark+, in which case you will for the same reason want to load that library after you have modified ‘bookmark-default-file’. An example of this is Icicles, which loads Bookmark+ if Bookmark+ is in your ‘load-path’.

In general, with Bookmark+ I recommend that you simply set option ‘bookmark-default-file’ once and for all at the outset, preferably by customizing it. You can use ‘bmkp-switch-bookmark-file-create’ at any time to switch to a different bookmark file - it is bound to ‘C-x x L’. You can also invoke it in your init file, provided Bookmark+ has already been loaded.

See Also: Using Multiple Bookmark Files

Overview of Bookmark+ Features

Here is an overview of some of the features that Bookmark+ provides. Some of these are detailed further below.

Richer bookmarks. They record more. They are more accurate.

Additional ways to bookmark.

Additional types of bookmarks.

Bookmark+ adds over 70 types of bookmark. (You can see what they all are by invoking function ‘bmkp-types-alist’.) Here are the main ones:

If option ‘bmkp-desktop-jump-save-before-flag’ is non-‘nil’, and if the current desktop was made current by jumping to a bookmark, then it is saved before jumping to the next desktop. If you want to save the last desktop jumped to when you quit Emacs, then add ‘bmkp-desktop-save-as-last’ to ‘kill-emacs-hook’.

In particular, note that you can use the following kinds of bookmarks to quickly switch among different projects (sets of bookmarks): Dired, Dired tree, bookmark-list, bookmark-file, and desktop bookmarks.

Type-specific jump commands.

Define your own bookmark types.

Just as for vanilla Emacs, you can easily define your own bookmark types, by defining a function to create its record, using function ‘bookmark-make-record’, or by binding variable ‘bookmark-make-record-function’ for a given context.

You can also make jumping to a new type of bookmarks type-specific, usable with ‘bmkp-jump-to-type’ (` C-x j :’) or with your own type-specific jump command.

For that, you need to do this:

1. Define a function bmkp- TYPE-alist-only, which returns an alist of bookmarks that are only of your new TYPE, for use with ‘bookmark-completing-read’. The alist should have the same form as ‘bookmark-alist’. (And you can use your alist for more than just completion.)

2. Evaluate ` (bmkp-define-history-variables)’, to add a history variable for your type, again, for use with ‘bookmark-completing-read’.

You can use macro ‘bmkp-define-type-from-hander’ to define a simple bookmark type that’s based only on a given handler. You pass it the TYPE name and HANDLER name as arguments. It does #1 and #2 above, plus it defines:

(Remember that to use any of the Bookmark+ macros directly you’ll need to load library ` bookmark+-mac.el’.)

Extensive menus.

Improvements for the bookmark-list display.

This is buffer ‘*Bookmark List*’, aka the bookmark “menu list” (a misnomer), which you display using ‘C-x x e’ (or ‘C-x r l’). See Bookmark List Display.

Multiple bookmark files.

Although vanilla Emacs lets you load different bookmark files, it does not support this feature well, and the behavior can even be contradictory. With Bookmark+ you can easily (a) switch among alternative bookmark files or (b) load multiple files into the same session, accumulating their bookmark definitions. The last file you used is the default when you choose a file to switch to, so it is easy to go back and forth between two bookmark files. See Using Multiple Bookmark Files.

Dedicated keymaps as prefix keys.

All of these prefix keys correspond to prefix-map variables, so you need not use these particular prefixes. You can bind these maps to any prefix keys you want. These are the maps, together with their predefined bindings.

Those are the prefix keys that are available by default. To change them, just customize these user options, each of which is a list of the key sequences to use as prefix key.

(^X here is actually the Control-X character.)

Keymaps ‘bmkp-set-map’ and ‘bmkp-tags-map’ are always on ‘bookmark-map’, whatever prefix keys it is on. So if, for example, you customize ‘bmkp-bookmark-map-prefix-keys’ to be ("^Xp" [f9]) then the keys in ‘bmkp-set-map’ have both prefix ‘C-x x c’ and prefix ` <f9> c’.

In addition to keys on Bookmark+ keymaps, Bookmark+ binds some mode-specific bookmarking commands in some other modes: Occur, Compilation (including Grep), Buffer-menu, EWW, Gnus, Info, Man, Woman, W3M, and Dired (if you use library Dired+). These keys let you set or jump to bookmarks specific to the modes.

Helpful help.

Jump-destination highlighting.

When you jump to a bookmark, the destination (position) is highlighted temporarily using crosshairs, to make it stand out. Option ‘bmkp-crosshairs-flag’ controls this, and this feature is available only if you also use library crosshairs.el.

Visual bookmarks (highlighting).

You can highlight the locations of bookmarks, either automatically or on demand. You control what kind of highlighting, if any, is used for which bookmarks. This feature requires that you have library bookmark+-lit.el in your ‘load-path’ (it will then be loaded by bookmark+.el).

Better, user-configurable bookmark-name defaults.

See the doc strings of command ‘bookmark-set’ (Bookmark+ version) and options ‘bmkp-new-bookmark-default-names’ and ‘bmkp-default-bookmark-name’.

Synergy with Icicles.

Icicles works with Bookmark+ to provide enhanced bookmark jumping (visiting), setting, and help. It gives you a bookmark browser, and lets you bookmark and tag files on the fly. See Use Bookmark+ with Icicles.

Bookmark Basics

Bookmark+ builds on vanilla Emacs bookmarks. If you are familiar with the latter, then you can skip this section, which mostly reviews the former. However, this section also introduces some Bookmark+ concepts and features that are detailed in other sections.

In Emacs bookmarking these three things are different but related:

1. the bookmark list

2. the bookmark file

3. the bookmark-list display (buffer ‘*Bookmark List*’, aka the bookmark “menu list”, a misnomer)

It is important to keep these three straight and understand their differences in practice, in particular, when they do and do not represent the same set of bookmarks.

#1 is in memory. It is the current set of bookmarks. When you add, rename, delete, etc. a bookmark, this list is updated.

#2 is on disk. It is a persistent record of a set of bookmarks.

The bookmark list (#1) is the current value of internal variable ‘bookmark-alist’. The bookmark file (#2) can be anywhere. Its default filename is the value of user option ‘bookmark-default-file’.

The bookmark list is typically initialized from the bookmark file — referred to as loading your bookmarks, but you can also create bookmarks (adding them to the list) without ever saving them to disk.

The bookmark list can be saved to the bookmark file — referred to as saving your bookmarks — either automatically or on demand. But it is not necessarily saved. Even if it has been saved in the past, that does not mean that at any given time the bookmark list corresponds exactly to the bookmark file.

The list and the file can often become out of sync. In an Emacs session, the bookmark list rules. After an Emacs session, the bookmark file rules (it is all there is). You can use ‘C-x x L’ (‘bmkp-switch-bookmark-file-create’) to sync (revert) the list to reflect the file — just accept the default value, “switching” to the same file.

The bookmark-list display (#3) is a snapshot view of the bookmarks in the bookmark list. As such, what you see there reflects the state of the bookmark list at some point in time. So here again, the two, list and display, can be out of sync. Hitting ‘g’ in the bookmark-list display refreshes it to accurately reflect the current bookmark list (#1). Some other operations in the display also keep it synced with the list.

Using a prefix argument (‘C-u g’) syncs the display (#3) and the list (#1) to the file (#2). This can be useful when some other process (e.g., another Emacs session) updates the bookmark file or when you want to abandon changes to the current bookmark list and any of the current bookmarks. Outside the bookmark-list display, you can use command ‘bmkp-revert-bookmark-file’ to do this.

You can load different bookmark files, either adding their bookmarks to those already in the current bookmark list or replacing them.

The most important takeaway from this section is that #1 (list), #2 (file), and #3 (display) can be out of sync, and they often are. And that can be useful.

Until now, everything said in this section is true of vanilla Emacs as well as Bookmark+. Bookmark+ adds some flexibility regarding the use of multiple bookmark files, and it can save the last state of the bookmark-list display for later reuse.

The saved state of the display is restored when you show the display after quitting it (‘q’) in the same session or quitting Emacs, but only if the bookmark file whose location it recorded is the same as the current bookmark file.

It would not make sense to display a completely different set of bookmarks from those that are currently loaded. The display must always reflect the current bookmark list (even if it sometimes reflects it imperfectly, because it is a snapshot). So if the bookmark file that is loaded is different from the one that was recorded for the display state, the recorded state is ignored.

Automatic Saving

Before getting into the topic of automatic saving, let me say this clearly once: Back up your bookmark file(s)!

(Bookmark+ creates backups when your bookmark file is saved. Until bug #12507 is fixed, vanilla Emacs does not.)

I recommend that you set option ‘bookmark-version-control’ to ‘t’, so that you get numbered backups.

If you do use numbered backups then you might also want to customize option ‘delete-old-versions’, setting the value to ‘t’, so that you are not bothered by this prompt each time bookmarks are saved:

Delete excess backup versions of <YOUR-INIT-FILE>? (y or n)

See also nodes ‘Backup Names’ and ‘Backup Deletion’ in the Emacs manual.

User option ‘bookmark-save-flag’ controls whether and how often to automatically save the bookmark list to the bookmark file. You can toggle this option using **` M-~**’ in the bookmark-list display.

In the bookmark-list display, you can tell whether individual bookmarks have been modified since the last save: they are marked with ‘*’. I believe that this indication is robust and accurate (if not, please report a bug), but a word of caution: do not depend on it. The only way to be sure that your bookmarks have been saved is to save them. ;-)

Is there a way to _un_modify a single bookmark that you have changed? No, not unless it is the only one you modified. If you revert to the bookmarks as last saved, then all changes to all bookmarks (including addition and removal of bookmarks) are lost. If you want to work carefully when making multiple changes, then save any modifications you are sure of before you move on to others. If only one bookmark is modified then reverting to the bookmark file effectively unmodifies that bookmark.

When you consult the doc for option ‘bookmark-save-flag’ you see that besides values of ‘nil’ and ‘t’, meaning off and on, it can have a value that is the number of bookmark modifications to allow before automatically saving. If the value is 10, for instance, then the 11th modification triggers automatic saving.

But a modification means any change to any bookmark. Typically, you are more interested in considering all of the changes caused by a given command as one modification. Why? Suppose you use a command such as ` T > +’ (‘bmkp-bmenu-add-tags-to-marked’), which adds a set of tags to each of the marked bookmarks. Even if there have been no other modifications since you last saved bookmarks, if there are more marked bookmarks than your setting of ‘bookmark-save-flag’ then automatic saving will kick in in the middle of the command. Some of the bookmarks with the added tags will be automatically saved. And that does not give you an opportunity to cancel the changes (e.g., by quitting without saving).

This is the reason for option ‘bmkp-count-multi-mods-as-one-flag’, whose default value is ‘t’, which means count all of a sequence of modifications together as one modification, as far as ‘bookmark-save-flag’ is concerned.

Different Types of Jump Commands

When you jump to a bookmark, you can use completion to specify the bookmark name. ‘bookmark-jump’ and ‘bookmark-jump-other-window’, bound to ‘C-x j j’ and ‘C-x 4 j j’, are general commands. Their completion candidates include all of your bookmarks. With Bookmark+ you can easily have a large number of bookmarks.

To provide more specificity, Bookmark+ provides many different bookmark jump commands. If you want to jump to a bookmark of a specific type, such as Info, you can use a Bookmark+ command that is specific to bookmarks of that type: only those bookmarks are completion candidates.

There are thus type-specific commands: ` bmkp-_dired_-jump’, ` bmkp-info-jump’, and so on, bound to ` C-x j _d_’, ` C-x j _i_’, and so on. There are also commands to jump to bookmarks for the current buffer or for particular buffers or files (see Bookmarks for Specific Files or Buffers).

All bookmark jump commands are bound to keys that have the prefix ‘C-x j’. There is an other-window version of most jump commands, and it is bound to the same key as the same-window command, except the prefix is **` C-x _4_ j**’, not **‘C-x j’**. For instance, ‘bmkp-dired-jump-other-window’ is bound to ‘C-x j 4 d’.

(In the bookmark-list display, you can use just ‘j’ instead of ‘C-x 4 j’, and just ‘J’ (uppercase) instead of ‘C-x j’.)

More precisely, the bookmark jump commands are on the prefix maps ‘bmkp-jump-map’ and ‘bmkp-jump-other-window-map’, which have the default bindings ‘C-x j’ and ‘C-x 4 j’. You can bind these maps to any keys you like, by customizing options ‘bmkp-jump-map-prefix-keys’ and ‘bmkp-jump-other-window-map-prefix-keys’.

If you do not remember the different type-specfic bindings, you can use commands ‘bmkp-jump-to-type’ and ‘bmkp-jump-to-type-other-window’ (**` C-x j :**’ and **` C-x 4 j :**’). They work for any type, prompting you first for the type, then for a bookmark of that type (only).

There are several commands for jumping to a bookmark with tags. The completion candidates can be those bookmarks that have all tags in a given set, some tags in a given set, all tags matching a regexp, or some tags matching a regexp. You are prompted for the set of tags or the regexp to match.

These commands all have the prefix key *` C-x j _t_**’. The suffix key is **`‘’** for “all” and **\ +**’ for “some”. The regexp-matching commands precede the suffix key with **` %**’. For example, ` C-x j t % +’ jumps to a bookmark you choose that has one or more tags that match the regexp you input.

There are some type-specific jump commands for bookmarks with tags. The key sequences for these include a key that indicates the bookmark type, after the ‘t’ indicating tags. For example, commands for jumping to a file or directory bookmark having certain tags use the prefix ‘C-x j t f’ (‘f’ for file). Similar commands for autofile bookmarks have prefix ‘C-x j t a’ (‘a’ for autofile).

For example, ` C-x j t f % *’ jumps to a file or directory bookmark you choose, where all of its tags match a regexp, and ` C-x j t a +’ finds a file tagged with at least one of the tags you input.

In addition to the ordinary autofile “jump” commands, there are ‘find-file’ versions: they read a file name using ‘read-file-name’, instead of completing a bookmark name – see Autofile Bookmarks. These commands are available starting with Emacs 22.

Bookmark names are global. File names are not; that is, the nondirectory portion is not. Suppose you have two similar directories with some like-named files, perhaps tagged in similar ways. Imagine image files of your vacations organized in different directories by year. It is sometimes useful to narrow your focus to the file bookmarks in one directory.

Commands such as ‘bmkp-file-this-dir-jump’ (` C-x j . f’) offer as completion candidates only bookmarks for files and subdirs in the current directory (‘default-directory’). For tags, there are equivalent commands. For example, ` C-x j t . % *’ is the same as ` C-x j t f % *’, but the destinations are limited to files in the current directory. All of the “this-dir” file jump commands are bound to the same keys as the general file jump commands, but with **`.**’ instead of ‘f’.

Remember that Bookmark+ collects lots of commands on only a few predefined prefix keys, primarily as a mnemonic device. Nothing requires you to use the long key sequence ` C-x j t f % *’ to visit a file that has a given set of tags. It is expected that you will bind short key sequences to commands that you use often.

The ‘C-x j’ and ‘C-x 4 j’ bindings are global. In addition, in some modes ‘j’ is bound to the corresponding type-specific jump command. For example, in Info mode, ‘j’ is bound to ‘bmkp-info-jump’. (Dired is an exception here: ‘J’ is used instead of ‘j’, since ‘j’ is already taken for ‘dired-goto-file’.) These commands are also added to the mode’s menu-bar menu.

In Dired mode, ‘C-j’ is bound to a special Dired-specific jump command, ‘bmkp-dired-this-dir-jump’, whose destinations all use the current directory (‘default-directory’). The aim of ‘C-j’ is not to change directories but to change to a different set of Dired markings, switches, inserted subdirectories, or hidden subdirectories for the same Dired directory.

In addition to the predefined bookmark types, which you can use as described above, you can define a “type”-specific jump command for any set of bookmarks. That is, you can use any specific set of bookmarks as the completion candidates for a new jump command. Such a set is really only a pseudo-type: the actual bookmarks can each be of any type.

You could use this feature, for example, to define a jump command for the bookmarks that belong to a given project.

One way to define such a command is to first mark the bookmarks that you want to be the completion candidates, then use ‘C-c C-j’ (command ‘bmkp-bmenu-define-jump-marked-command’) in the bookmark list.

The ‘*Bookmark List*’ display defines a set of bookmarks, even without markings. So does each bookmark of type bookmark list, that is, a bookmark corresponding to a particular ‘*Bookmark List*’ display state – see State-Restoring Commands and Bookmarks.

You can capture the set of bookmarks corresponding to a ‘*Bookmark List*’ display for use in navigation, that is, as the current navigation list. Navigation here includes jumping and cycling – see Cycling, Navigation List.

To capture in the navigation list the bookmarks corresponding to either the current ‘*Bookmark List*’ display or a bookmark-list bookmark, use ‘C-x x B’, which is bound to command ‘bmkp-choose-navlist-from-bookmark-list’. To then jump to a bookmark from such a navigation list, use ‘C-x j N’ or ‘C-x 4 j N’ (‘bmkp-jump-in-navlist’ or ‘bmkp-jump-in-navlist-other-window’).

Bookmark Annotations

With Bookmark+ you can bookmark many kinds of Emacs object. Bookmarks record locations – that is their primary purpose. They can also record annotations: general free-text descriptions of your choosing. An annotation is thus metadata that is associated with a bookmark. You can use it for any purpose you like.

“Annotation” is arguably not the best name for what this is or does. But that’s the name vanilla Emacs uses for it, so Bookmark+ does too.

Command ‘bookmark-show-annotation’ shows an annotation in read-only mode. You can use ‘C-x C-q’ in the annotation buffer to switch to edit mode (and back again).

You can use command ‘bookmark-edit-annotation’ or ‘bmkp-annotate-bookmark’ anywhere to edit the annotation for a bookmark. For ‘bookmark-edit-annotation’, you can choose among the bookmarks that already have annotations. With a prefix arg, you can choose any bookmark (and so create an annotation). Using ‘bmkp-annotate-bookmark’ is the same as using ‘bookmark-edit-annotation’ with a prefix arg.

The annotation edit buffer starts with some text that isn’t saved as part of the annotation. It shows some editing instructions, the user name, system name, and date+time of the current edit.

In the annotation edit buffer, make your changes and then use ‘C-c C-c’ to save the result. Use ‘C-x C-k’ if you don’t want to save the changes. You can also use ‘C-x C-q’ and then ‘y’ to confirm reverting the changes.

Non-‘nil’ user option ‘bookmark-automatically-show-annotations’ means that a bookmark’s annotation is popped up whenever you jump to the bookmark. If the non-‘nil’ value is ‘edit’ then the annotation buffer is in edit mode; if it is any other non-‘nil’ value then the buffer is in show (read-only) mode.

In the ‘*Bookmark List*’ display, bookmarks with annotations are marked by an ‘a’ character to the left of the bookmark name. You can use ‘a a’ to show the annotation for the bookmark on the current line. You can use ‘a e’ to create an annotation or edit an existing annotation for it. You can use ` a >**’ to edit annotations for all of the marked bookmarks. You can use **‘a A’ to show a list of the names and annotations of all annotated bookmarks.

A bookmark annotation is stored as part of the bookmark itself. For this reason, you typically want to keep the text fairly short. In Bookmark+, the mode for viewing and editing a bookmark annotation is Org mode, by default. (To change the mode used, customize option ‘bmkp-annotation-modes-inherit-from’.)

You can obtain the effect of using a longer annotation, and some other advantages as well, by using an “**annotation forward**” in the annotation text. This is short text that serves only as a pointer to an external file, URL, or another bookmark.

Whenever you show the annotation of a bookmark (via ‘a a’ in the ‘*Bookmark List*’ display, ‘bookmark-show-annotation’, or ‘bookmark-automatically-show-annotations’) and the annotation contains such a pointer (only one such is used), the effect is to visit the pointer’s destination. That is, showing the annotation goes to the forward destination, instead of showing the annotation text stored with the bookmark. (You can still see the latter, by editing the annotation.)

So for example, you can use bookmarks to one or more Org files to annotate (provide notes about, or metadata for) one or more other bookmarks. For example, set a bookmark at some place in an Info manual, then write your own notes about that Info content in an Org file, bookmark that Org-file destination, and use that as a forward destination in your bookmark to that Info location.

You create an annotation forward for a bookmark by using one of these forms as the annotation text.

 bmkp-annot-file: "FILE"
 bmkp-annot-url: "URL"
 bmkp-annot-bmk: "BOOKMARK"

The double-quote characters are necessary here, so that you can include characters such as ‘SPC’ in the name. The text must be on the first line of the annotation (not counting the commented instruction lines). It can be preceded only by whitespace.

You can include other text in the annotation, after the external destination specification, and you can see or edit it when you edit the annotation (e.g., ‘a e’ in buffer ` *Bookmark List*’). But it is ignored when the annotation is only “shown” (e.g., ‘a a’).

In the ‘*Bookmark List*’ display, ‘M-down’ and ‘M-up’ move the cursor down and up a line, respectively, but they also show the annotation, if any, of the bookmark at the new cursor location.

Bookmark Tags

In addition to annotating bookmarks with arbitrary metadata, Bookmark+ bookmarks can also be tagged, as a way to organize them, which also means as a way to organize the objects that are bookmarked.

By tagging and tag in this context is meant associating keywords or other text with an object, typically in order to classify or characterize it. Tags are metadata about an object. This notion of tagging is sometimes called “delicious” tagging after the Web site www.delicious.com that popularized it (http://en.wikipedia.org/wiki/Delicious_(website)).

Be aware that there is another notion of “tag” associated with Emacs: that involving Emacs TagsFiles, which record the locations of function, variable, etc. definitions in source files. There is no relation between the two notions of “tag”.

A bookmark tag is a string (or a cons whose car is a string – see Bookmark Tags Can Have Values. You can add as many tags as you like to any bookmark, and multiple bookmarks can have the same tag(s). In fact, that’s the whole idea behind using them for organizing.

This feature is unrelated to the fact that bookmarks record locations and are useful for navigating. You can, if you want, use bookmarks to tag files in various ways purely for purposes of organizing them (e.g. into projects), whether or not you ever use the bookmarks as a way to visit them.

For example, if you use Dired+ (library dired+.el), then you can use ‘M-b’ (‘diredp-do-bookmark’) in Dired to create an autofile bookmark for each of the marked files and subdirectories in the Dired buffer. Even if you never use those bookmarks for navigating to their targets, you can use them with tags to organize the targets and thus operate on subsets of the marked files and subdirectories.

And if you use libraries Dired+ and Highlight (highlight.el) then autofiles are highlighted specially in Dired, and the highlighting indicates whether the file is tagged.

DrewsEmacsDiredAutofiles

By default, you create bookmarks without tags and add tags to them later. If you prefer, you can customize option ‘bmkp-prompt-for-tags-flag’ to non-‘nil’ so that you are prompted to add tags immediately whenever you set (create or update) a bookmark.

There are also some commands, such as ‘bmkp-tag-a-file’ (**` C-x x t + a**’) and **‘bmkp-untag-a-file’** (**‘C-x x t - a’**), that always prompt for tags to add or remove. (In general, the key ‘a’ is used in key sequences for autofile bookmarks.)

When you are prompted to enter a tag, you type some text then hit ‘RET’. If you want to include a newline character in the tag itself, use ‘C-q C-j’ (‘C-j’ is the newline character). You can use ‘C-q’ this way to enter any character. If you do use complex strings as tags then you might prefer to simply edit a bookmark’s tags in a separate buffer. You can do that using ‘C-x x t e’ (or ‘T e’ in the bookmark-list display).

Whenever you are prompted for a tag you can use completion. The completion candidates available are the tag names defined by option ‘bmkp-tags-for-completion’. The default value of this option is ‘current’, meaning use only the tags from the bookmarks in the current bookmark list as candidates. You can customize the option to include specific tags or the tags from bookmarks in specific bookmark files.

You can use command ‘bmkp-list-all-tags’ to list all of the tags defined by option ‘bmkp-tags-for-completion’ or, with a numeric prefix argument, only the tags corresponding to the current bookmark file. You can list the tag names only or (using a non-negative prefix arg) show the full tag definitions, which include any associated tag values (see Bookmark Tags Can Have Values) for information about tag values).

To make tags more useful, Bookmark+ provides lots of commands: for adding, removing, copying, pasting, and renaming tags; commands for jumping to bookmarks with particular sets of tags; and commands for marking or unmarking (in buffer ‘*Bookmark List*’) bookmarks that are tagged in various ways.

Most commands pertaining to tags are by default on prefix key ‘C-x x t’ — use ‘C-x x t C-h’ to see them. In buffer ‘*Bookmark List*’, commands pertaining to tags are on prefix key ‘T’ — use ‘T C-h’ to see them. And remember that you can use **` C-h >**’ to describe all of the marked bookmarks, in the current sort order. The bookmark descriptions include the tags.

When combined with other Bookmark+ commands (e.g. search, query-replace) that apply to the marked bookmarks in the ‘*Bookmark List*’ window, you can really do quite a lot using bookmark tags. Use your imagination!

See Also:

Bookmark Tags Can Have Values

Bookmark tags are simply names (strings) when you create them. Nearly all of the predefined operations that use tags use these names: sorting, marking, jumping, and so on. But you can in fact add an associated value to any tag. This means that a tag can act just like an object attribute or property: it can be a name/value pair.

To add a value to a tag that has none, or to change the current value of a tag, you use command ‘bmkp-set-tag-value’, which is bound to ‘T v’ in the bookmark list and bound to ‘C-x x t v’ globally. You are prompted for the bookmark, the tag, and the new value.

A tag value can be a number, symbol, string, list, vector, and so on. It can be as complex as you like. It can be any EmacsLisp object that has read syntax, that is, that is readable by the Lisp reader. (Everything that is saved as part of a bookmark must be readable; otherwise, your bookmark file could not be read (loaded).)

Because tag values can be pretty much anything, you are pretty much on your own when it comes to making use of them. Bookmark+ does not provide predefined functions for using tag values. In general, tag values are something you will use with home-grown Lisp code for your own purposes.

However, you can easily make some interactive use of tag values with little effort. You can, for example, define a predicate that tests whether a bookmark has a tag value that satisfies some property (e.g. is a number greater than 3.14159265358979), and then you can use command ‘bmkp-bmenu-mark-bookmarks-satisfying’ to mark those bookmarks.

Tags that have the prefix "bmkp-" are reserved – do not name your own tags using this prefix. Currently, "bmkp-jump" is the only predefined bookmark tag. You can give this tag a value that is a function – it is called whenever the tagged bookmark is visited. Any Lisp-readable function value is allowed: a symbol or a lambda expression.

For example, to display Hello! when a bookmark is visited you can use this:

T v bmkp-jump RET (lambda () (message "Hello!"))

The function that is the value of a "bmkp-jump" tag is called just after the the standard hook ‘bookmark-after-jump-hook’ is invoked. You can use this tag to invoke functions that are specific to individual bookmarks; bookmarks can thus have their own, extra jump functions.

Hierarchical Structures of Bookmarks?

You can use tags to organize sets of bookmarks in various ways. But what about a simple, hierarchical (tree-shaped) structure like the one you use for bookmarks in a web browser? You can get a similar effect with Bookmark+ by just using a tag-naming convention such as this:

vacation/ vacation/2017/ vacation/2017/winter/ vacation/2017/winter/photos/ vacation/2017/summer/ vacation/2017/summer/photos/ vacation/2018/ ...

You need not tag any bookmarks with any particular part of such a pseudo-hierarchy. For example, you might tag some bookmarks with vacation/2017/winter/ and some with vacation/2017/winter/photos/, without bothering to have any that are tagged with just vacation/ or just vacation/2017/.

You are not limited to a single tree. You can have a tag such as vacation/2017/winter/ and a tag such as work/projects/2017/alpha/, without any need for those to have a common ancestor.

How can you use such a tagging scheme?

When you jump to a bookmark using a command that asks for tags, such as ` C-x j t +’ (‘bmkp-some-tags-jump’), you can use completion. So you can, for example, type ‘vac TAB’ to show all of your vacation tags (in ‘*Completions*’), and drill down, completing more, to pick whichever particular vacation tag you’re interested in. This is similar to traversing a web-browser tree-like bookmarks menu. But jump commands that use tags let you match any number of tags at the same time, not just one.

Completion against the set of existing tags is also available when you add tags to a bookmark. And if option ‘bmkp-prompt-for-tags-flag’ is non-‘nil’ then you are prompted to add tags whenever you create or update a bookmark. But unlike the case for web-browser bookmark creation, classifying a bookmark when you create it or update it is optional. You can always add tags later, or not at all.

Such a purely conventional, pseudo-hierarchy might sound like a silly hack, but it is at least as quick to use as is adding a bookmark to your tree of browser bookmarks. And it is more useful, because the organization is more flexible and you can have multiple, independent hierarchies.

The tagging scheme just described can help you keep track of things, even though it is very simple. There is nothing special about it. You might come up with other conventions for classifying tags, which you find more convenient or more powerful. And remember that tags can be more than just names. They give you the full power of Lisp values - do with them whatever you like.

Function, Sequence, Variable-List,... Bookmarks

Bookmarks are typically thought of only as recorded locations. Invoking a bookmark, called “jumping” to it, traditionally means just visiting its location. Bookmark+ looks at bookmarks in a more general way than that. A bookmark is a shortcut of some kind – nothing more. It is typically persistent, but it need not be (see Temporary Bookmarks).

A given type of bookmark is defined by its handler function, which can do anything you like. We’ve already seen the examples of region bookmarks, which restore the active region, and Dired bookmarks, which restore Dired markings, switches, inserted subdirectories, and hidden (sub)directories.

A function bookmark simply invokes some function — any function. You can, for instance, define a window or frame configuration and record the configuration as a bookmark. Then jump to the bookmark to switch contexts. (You can also bookmark a desktop and jump to that.)

Function bookmarks might not seem too interesting, since there are other ways to invoke functions in Emacs. But the other features of Bookmark+ combine with this feature. You can, for instance, tag function bookmarks.

And you can combine them, invoking the functions sequentially. This is a particular case of using a sequence bookmark, which simply records a sequence of bookmarks. The bookmarks in a sequence can be of any kind, including other sequence bookmarks.

Command ‘bmkp-make-function-bookmark’ (‘C-x x c F’) creates a function bookmark — you give it a function symbol or a lambda expression.

A function bookmark can invoke a keyboard macro instead of a function. With a prefix argument, ‘bmkp-make-function-bookmark’ creates a function bookmark from the last keyboard macro. Jumping to the bookmark executes the keyboard macro. A bookmark is thus one way to make a keyboard macro persistent.

If you provide a prefix argument to the bookmark jump command or key that invokes a function bookmark, it is passed along to the function. If the bookmark invokes a keyboard macro then the prefix argument determines how many times the macro is invoked.

The most general way to create or update a sequence bookmark is using command ‘bmkp-set-sequence-bookmark’ (‘C-x x c s’). You are prompted for the sequence bookmark name and the names of the bookmarks that form its sequence and are thus invoked by it sequentially.

If the sequence bookmark already exists then a prefix argument determines whether the bookmarks you name are added to the existing sequence or replace it, and if added, whether before or after the bookmarks already in the sequence.

Command ‘bmkp-wrap-bookmark-with-last-kbd-macro’ (‘C-x x c C-k’) returns a sequence bookmark that invokes a bookmark you name and then invokes the last keyboard macro. You are prompted for the names of both bookmarks. If the sequence bookmark does not yet exist then it is created. (The bookmark to be added to the sequence need not exist yet, and it is not created by adding its name to the sequence.)

If you enter the same name for the sequence bookmark and the bookmark to wrap with the keyboard macro, then the macro is simply added to that (sequence) bookmark.

For example, if you enter ‘my-seq’ for both of the ‘bmkp-wrap-bookmark-with-last-kbd-macro’ prompts, then the last keyboard macro is added to sequence bookmark ‘my-seq’. Bookmark ‘my-seq’ need not exist yet, in which case it is created, with the keyboard macro as its only member bookmark.

If the bookmark to add to the sequence is itself a different (existing) sequence bookmark, then its member bookmarks are added to the sequence being updated (or created), either before or after its existing members, according to the prefix arg (which is passed to ‘bmkp-set-sequence-bookmark’).

Command ‘bmkp-bmenu-make-sequence-from-marked’ creates a sequence from the marked bookmarks in the bookmark-list display, in their current order.

If you use library Dired+ then you can use command ‘diredp-do-bookmark-dirs-recursive’ to create a Dired bookmark for the current Dired buffer and each of its marked subdirectories. Each of those subdirectories is handled similarly, and so on, recursively. This command also creates a sequence bookmark that includes all of these Dired bookmarks, so that it represents a tree (hierarchy) of Dired buffers that are opened together. This provides an alternative to inserting all of the relevant subdirectories into the same Dired buffer. With a prefix argument, all of the descendent Dired buffers are included, whether or not they are marked.

You can also create a function bookmark directly from a keyboard macro, using command ‘bmkp-set-kmacro-bookmark’. And you can save the current set of keyboard macros as a bookmark, using command ‘bmkp-set-kmacro-list-bookmark’ - jumping to it restores all of the macros.

A variable-list bookmark saves and restores the values of a set of variables. Command ‘bmkp-set-variable-list-bookmark’ prompts you for the variables to include in the list and then sets the bookmark. Command ‘bmkp-jump-variable-list’ (‘C-x j v’) restores the recorded variable values for the bookmark’s buffer. You can also create variable-list bookmarks non-interactively, using function ‘bmkp-create-variable-list-bookmark’.

If you use library zones.el (see Zones and MultipleNarrowings), then you can move among multiple restrictions (narrowings) in a buffer. The restrictions are stored in buffer-local variable ‘zz-izones’. Command ‘bmkp-set-izones-bookmark’ bookmarks this value for the current buffer. Jumping to such a bookmark restores the saved ring/stack of restrictions.

Little Persistent Named Nothings

OK, so a bookmark need not “go” anywhere. Function, sequence, variable-list, and some other kinds of bookmarks have no real “location” to move to or restore. But the bookmarks talked about so far at least have an associated action: you can “jump” to them, even if “jump” can mean a arbitrary action that might have nothing to do with reaching a destination.

You can also have a non-invokable bookmark, that is, one that you cannot jump to. This is a bookmark whose handler is the function ‘ignore’, which does nothing.

What’s the point of that? To record something persistently, without needing to manage the file(s) you record it in, and to be able to access that something by name.

As an example, library Isearch+ provides one such use case. It lets you interactively add, modify, and remove Isearch filter predicates on the fly, providing more power and flexibility in searching.

(A filter predicate is a function that accepts the current search-hit limits as arguments. If it returns ‘nil’ then that search hit is excluded from searching; otherwise it is included.)

You can also, on the fly, encapsulate the current suite of filter predicates as a new filter predicate. That is, you can manipulate a complex sequence of filters as a single predicate, using a simple name. And you can save the definition of that new predicate in a file, so you can use it again in future Emacs sessions.

Alternatively, you can just bookmark the search predicate. The data saved in the bookmark is the suite of filters that is the advised value of ‘isearch-filter-predicate’ at the time of bookmarking.

Then, in a future Emacs session, while Isearching you can hit a key and enter the bookmark name (with completion), to apply that suite of filters again.

Bookmarking is easier than defining a new predicate and bothering with a file to save it in. This is the kind of thing that bookmarks are for: persistently saving named bits of data for later retrieval by name.

Because the saved data in this case (the filter definition) has no use outside the context of searching, there is no way to invoke it – no jump action. Its handler is ‘ignore’.

You can apply all Bookmark+ features to non-invokable bookmarks: sort, edit, tag – whatever. Use Bookmark+ to organize them, even if you cannot invoke them.

Non-invokable bookmarks are shown using face ‘bmkp-no-jump’ in the bookmark-list display.

It is also possible for a bookmark to have a handler other than ‘ignore’, so that it is invokable, but that its jump action is appropriate only in certain contexts. This is the case, for instance, for an Icicles search-hits bookmark. You cannot invoke it outside the context of Icicles searching. For this reason, these bookmarks are also shown with face ‘bmkp-no-jump’ in the bookmark-list display.

Editing Bookmarks

In vanilla Emacs, you can edit the annotation associated with a bookmark. And you can rename a bookmark. But that is all. There is no easy way to really edit a bookmark.

With Bookmark+:

For all but the first of these, you are placed in a separate editing buffer. Use ‘C-c C-c’ when you are done editing, to save your changes. (To cancel, just kill the buffer: ‘C-x k’.)

You can also clone (duplicate) a bookmark, using ‘M-n’, and then edit any parts of it (e.g. using ‘e’). By default, the clone has the same name, but with "<2>" appended. With a prefix arg you are prompted for the name. Outside of the bookmark list you can use ‘C-x x 2’ to clone a bookmark.

There are many more keys and commands for editing bookmark tags. You can copy tags (‘C-x x t c’) from one bookmark and paste them to others, either replacing the original tags (‘C-x x t C-y’) or adding to them (‘C-x x t q’). You can be prompted for some tags to add (` T +**’) or _remove_ (**‘T -’**) from a bookmark. You can _delete_ a tag from all bookmarks (**‘T d’**). You can _rename_ a tag everywhere (**‘T r’). And you can set a tag’s value.

As usual, all such commands are also available on the Bookmark+ menus. The menus provide quick reminders of the available keys, as does the help from **` ?**’ in the bookmark-list display.

Bookmark Records: What A Bookmark Looks Like

It’s worth dispelling some of the mystery about what a bookmark is by mentioning what it looks like. This can help when you edit a bookmark record. The first thing to mention is that the basic structure of a bookmark record is described in the doc string of variable ‘bookmark-alist’ – but I’ll repeat some of that info here.

A bookmark record is nothing more than a list whose first element is a string, the bookmark name. The other list elements are properties: key+value pairs that define the bookmark data. Each such pair is a cons: a nonempty list or a dotted list.

The car of the property is its name (a Lisp symbol). The cdr is its value. What the value can be depends on the property – in general it can be any Lisp value (number, string, list, symbol, etc.). A property with a null cdr means the same thing as having no such property present. For example, having the empty property ` (tags)’ is the same as having no ‘tags’ property at all.

There is nothing more to it: properties can be anything you like, provided you provide some code to recognize them and do something with them.

Of course, the types of properties you use most (maybe always) are predefined, and the vanilla bookmark.el code and the Bookmark+ code recognize and use them. The most important and most typical property is this: ` (filename . "/some/file/name.txt")’, that is, a cons whose car is the symbol ‘filename’ and whose cdr is the name (a string) of the bookmarked file.

With that in mind, you can see that renaming a bookmark just means changing the string that is its car. And relocating a bookmark just means changing the string that is its ‘filename’ – e.g., from ` (filename . "/home/foo.el")’ to ` (filename . "/some/other.xml")’.

If you already have a bookmark file, typically ` ~/.emacs.bmk’, take a look at the bookmark records in it. A typical bookmark also has these properties, in addition to ‘filename’: **‘position’**, **‘front-context-string’**, and **‘rear-context-string’**. You can guess what they are – if not, see the doc string of ‘bookmark-alist’.

A Bookmark+ bookmark typically has some additional properties that you can also guess. Properties ‘time’ and ‘visits’ are updated automatically each time you access the bookmark.

Some bookmarks have a ‘handler’ property whose value is a function that “jumps” to the bookmark “location”. I put those two terms in quotes here because a handler is really just any function – it can do anything you like, and there need not be any associated location.

Some Bookmark+ bookmarks, including autofile bookmarks, just “jump” to a file. The position in the file is unimportant, and “jumping” does not necessarily mean visiting the file with Emacs. In effect, such bookmarks are just wrappers around the file, letting you get the advantage of Bookmark+ features (tags etc.) for a file. Such bookmarks, which you can create using ‘C-x x c a’ or ‘C-x x c f’, contain a ‘file-handler’ property instead of a ‘handler’ property. The difference between the two is that the ‘file-handler’ value is a function (Lisp function or shell command) to be applied to the file, not to the bookmark.

Remember: A bookmark is just a persistent bit of information, typically meta-information about a file and a position in that file.

I’m mentioning all of this to make the point that you cannot really hurt anything if you edit a bookmark record and you mess things up. The worst you can do is mess up all of your bookmarks by making the file unreadable as Lisp data. (It’s always a good idea to back up your bookmark file from time to time.)

And if each bookmark record after you edit it is a cons with a string car then your bookmarks are generally OK, even if you might have ruined the details of one or two of them. Suppose you somehow mistakenly delete the ‘a’ in a ‘filename’ property, for instance. No big deal – that bookmark no longer has a recognizable target location, but the other bookmarks are still OK.

The most important property for Bookmark+ users (aside from ‘filename’) is probably ‘tags’. Its value (the cdr) is a list of strings or conses – the bookmark’s tags. When you create a tag, it is typically a string (just its name) – e.g. "blue". If you then give it a value as well, it becomes a cons with that string (the name) as car and the value as cdr – e.g. ` ("blue" . 42)’ or ` ("blue" moonbeam 42)’ – here the cdr is the list ` (moonbeam 42)’. Here is an example of a ‘tags’ property: ` (tags "hegel" ("blue" . honeypot) "darwin")’. Most of the time you will use strings as tags. See also Bookmark Tags Can Have Values.

When you edit bookmark records, just try to stay away from changing any properties that you are not familiar with. And make sure that when you’re done you have a proper Lisp list (open parens closed etc.). If you’ve never played with Lisp before, do not panic.

Be aware if you see dots (**` .**’) that they are important, and they must be surrounded by whitespace: **` .**’. The amount of whitespace never matters in Lisp (except inside a string etc.).

Such a dot just separates the car of a cons from its cdr. (What’s a cons? Just a car with a cdr!) If the cdr is a list then we typically drop the dot and the list’s parens: We write ` (b)’ instead of ` (b . ())’ and ` (a b)’ instead of ` (a . (b))’ or ` (a . (b . ()))’.

Finally, remember that when you set an existing bookmark again, e.g., you use ‘C-x r m’ and provide the name of an existing bookmark, the existing properties are generally lost. Some are automatically updated. Any that you might have added by editing are lost, and any that are provided by default by the bookmark handler are replaced. The only exceptions to this are the properties listed in option ‘bmkp-properties-to-keep’, which by default means properties ‘tags’ and ‘annotation’. Any existing tags and annotation are preserved when you update a bookmark.

Bookmark-List Views - Saving and Restoring State

The bookmark list (buffer ‘*Bookmark List*’) provides a view into the set of bookmarks. You can mark, sort, and hide (filter, omit) bookmarks — see BookmarkListDisplay. The state of the displayed bookmark list can thus change.

At different times, and in different contexts, different views can be useful. Bookmark+ lets you save the current state of the displayed list and later restore it. There are a couple of different ways to do this.

Quitting Saves the Bookmark-List State

If option ‘bmkp-bmenu-state-file’ is non-‘nil’, which it is by default, then Bookmark+ remembers the last state of the bookmark list when you quit it or you quit Emacs, and it restores that state when you show the list again (which could be in the next Emacs session). You can think of this feature as your Home page for bookmarks, giving you a stepping stone to the files and directories you use most.

If, for example, when you quit the bookmark list you are showing only bookmarks to Info nodes and UNIX manual pages, sorted in a particular way, and with some of them marked with ` >*’ for particular processing, then the next time you open the list the same state is restored: the same set of bookmarks is shown, in the same order, with the same markings. Deletion flags (‘D’) and modification indicators (**`‘’`) are purposefully not saved as part of the display state — they are lost when you quit the display.

You can turn off this automatic bookmark-list display state saving, if you want, by customizing option ‘bmkp-bmenu-state-file’ to ‘nil’. And you can toggle this option at any time, using **` C-M-~**’ in the bookmark list (command **‘bmkp-toggle-saving-menu-list-state’**). In particular, if you want your next visit to the bookmark list to start out with a _previously_ recorded state instead of the current state, just hit ` C-M-~’ before quitting the bookmark list.

State-Restoring Commands and Bookmarks

In addition to automatically saving/restoring the final bookmark-list display state, you can save this state at any time, any number of times, for later restoration. This gives you the ability to create multiple persistent views of your bookmarks.

There are two ways to do this:

When you use ‘C-x r m’ (‘bmkp-bookmark-set-confirm-overwrite’) in buffer ‘*Bookmark List*’ to create a bookmark-list bookmark, the current sort order, filter, regexp pattern, title, and omit list are saved as part of the bookmark. (These concepts are described below — see BookmarkListDisplay.) Jumping to such a bookmark restores all of these.

Alternatively, you can define a command that does the same thing, but without creating another bookmark – use ‘C-c C-c’ (‘bmkp-bmenu-define-command’) in the bookmark list to do this. You are prompted for the name of the new command. Use the command anytime (including in another Emacs session) to restore the bookmark list.

Define any number of such commands for the views you use. The file for saving the definitions (see option ‘bmkp-bmenu-commands-file’) is never overwritten, so you can also add other code to it manually, if you want. The file is read the first time the bookmark list is displayed in a given Emacs session.

The state that is saved and restored using a bookmark-list bookmark or a command defined using ‘C-c C-c’ is only a partial state. The current set of markings and some other information are not saved, in order to save disk space and save/restore time.

Sometimes, however, you really want to save the entire bookmark-list state, creating a full snapshot. You can use ‘C-C’ (aka ‘C-c C-S-c’, ‘bmkp-bmenu-define-full-snapshot-command’) to do that. This defines a command that restores the bookmark list completely. That is the same thing that happens automatically (by default) whenever you quit the bookmark list (or Emacs), but defining snapshot commands lets you have multiple saved states and switch to them at will.

Be aware, however, that full-snapshot command definitions can be quite large, since they each contain a copy of the current bookmark list and any accessory lists (hidden and marked bookmarks etc.).

Whether you use ‘C-c C-c’ or ‘C-c C-C’ to define a state-restoring command or you create a bookmark-list bookmark, you can create a sequence bookmark that combines such bookmark-list restoration with activation of other bookmarks. (To include a state-restoring command in a sequence, you need to first create a function bookmark that uses the command, and then include that bookmark in the sequence.)

Bookmarking without Visiting the Target

There are several use cases for bookmarking a target without visiting it:

1. In an Emacs buffer you come across a reference or a link to a file or a URL. You bookmark the target without bothering to visit it first. You do not really care which position in the file is bookmarked.

2. In Dired, you mark certain files and then bookmark all (each) of them, in one operation.

3. In a compilation buffer (e.g. ‘*grep*’, ‘*compile*’) or an occur or multi-occur buffer (‘*Occur*’), you bookmark one or more of the hits. Such a bookmark takes you to the appropriate position in the target file or buffer.

4. You bookmark a file that you might not even be able to visit in Emacs (in the sense of editing it in a buffer) – for example, a music file. “Jumping” to the bookmark performs an operation appropriate to the file – for example, playing music.

Bookmarking a File or a URL

You can use commands ‘bmkp-file-target-set’ and ‘bmkp-url-target-set’, bound by default to ‘C-x x c f’ and ‘C-x x c u’, to bookmark any file or URL. Completion is available, the default file name or URL being determined by the text at point. In addition to the file or URL, you are prompted for the bookmark name. (In general, the keys ‘f’ and ‘u’ are used in key sequences for file and URL bookmarks, respectively.)

Bookmarking the Marked Files in Dired

If you use Dired+, then you can bookmark all of the marked files (and subdirectories) in a Dired buffer at once, as autofiles, even if you normally do not or cannot visit those files in Emacs. These keys are available in Dired:

Each of these commands bookmarks each of the marked files and subdirectories as an autofile. By default, the bookmark file used for the latter two commands is in the current directory.

If you use multiple ‘C-u’ as a prefix argument for these commands, then you can bookmark all of the files in Dired, regardless of markings, as follows:

‘C-M-b’ not only bookmarks each of the marked files, it also creates a bookmark-file bookmark for that set of bookmarks. See Bookmark-File Bookmarks, below.

You can later “jump” to that bookmark to load its set of bookmarks. If you use ‘C-u’ when you jump to it, then you switch bookmark files, so that ‘C-x x e’ (or ‘C-x r l’) displays only the bookmarks created from the marked files. Without ‘C-u’, jumping to the bookmark-file bookmark simply loads its bookmarks into the current set of bookmarks.

Bookmarking Compilation, Grep, and Occur Hits

In a similar way, you can bookmark the file or buffer positions of selected hits in a compilation buffer (including ‘*grep*’) or an ‘occur’ or ‘multi-occur’ buffer.

‘C-c C-b’ in such a buffer bookmarks the target of the hit at point. ‘C-c C-M-b’ bookmarks the target of each hit in the buffer.

‘C-c C-M-b’ in these buffers is thus similar to ‘M-b’ in a Dired buffer. Unlike Dired, however, there is no way to mark such hits. Every hit is bookmarked.

Nevertheless, you can get the same effect. Just use ‘C-x C-q’ to make the buffer writable (e.g. temporarily), and then remove any hits that you do not want to bookmark. You can remove hits anyway you like, including by ‘C-k’ and by regexp (‘M-x flush-lines’ or ‘M-x keep-lines’).

See also: AutonamedBookmarks, bookmarking occur hits using autonamed bookmarks.

Bookmarking Files That You Cannot Visit with Emacs

You use lots of files that you never visit using Emacs, but that you might like to keep track of or access in other ways: music files, image files, whatever.

Here’s an example that one Bookmark+ user came up with: http://my.opera.com/purgat0ri/blog/2012/08/14/jury-rigging-a-collection-manager-in-emacs

You can define a new kind of bookmark for any file type you are interested in, implementing a bookmark handler for it that performs the appropriate action on it when you “jump” to it. That action needs to be expressible using an Emacs function, but it need not have anything to do with visiting the file in Emacs.

When you bookmark a target file that Emacs recognizes as an image or sound file, an appropriate handler is used automatically.

After you create individual bookmarks for, say, music or image files, you can use ‘P B’ in the bookmark-list display to show only those bookmarks, and then use ‘C-x r m’ to bookmark that state of the bookmark-list.

That bookmark-list bookmark in effect becomes a music playlist or an image library or slideshow. Jump to it anytime you want to listen to that set of music pieces or view those images. And you can use ‘C-x x B’ and then ‘C-x x next’ to cycle among the music pieces or images (slideshow). (See Cycling the Navigation List.)

Together with the use of bookmark tags, this gives you a handy way to organize and access objects of any kind. See Bookmark Tags.

You use option ‘bmkp-default-handlers-for-file-types’ to control which operation (bookmark handler) to use for which file type. This is a set of associations (an alist) with each key being a regexp matching a file name, and with each associated value being a Lisp sexp that evaluates to either a shell command (a string) or an Emacs function (a symbol or lambda form).

You can think of ‘bmkp-default-handlers-for-file-types’ as somewhat analogous to ‘auto-mode-alist’. But it maps file-name patterns to file actions instead of mapping them to buffer modes. And it has an effect only when you use certain commands.

The handler for the bookmark created invokes the shell command or the Emacs function with the file name as argument.

Here is an example option value:

(("\.ps$" . "gsview32.exe") ("\.html?$" . browse-url) ("\.doc$" . w32-browser))

This value causes creation of bookmarks that, when you jump to them, invoke:

The default value of ‘bmkp-default-handlers-for-file-types’ is taken from the value of option ‘dired-guess-shell-alist-user’ (from Dired X).

The associations are checked in order, and the first one that matches the given file name is used. You can thus order them to deal with overlapping file-name patterns.

If no matching file association is found in ‘bmkp-default-handlers-for-file-types’, and if option ‘bmkp-guess-default-handler-for-file-flag’ is non-‘nil’ (it is ‘nil’ by default), then Bookmark+ will guess a shell command to use. It does this by matching the file name against ‘dired-guess-shell-alist-default’ (also from Dired X). In Emacs 23 and later, if it finds no shell command that way then it guesses one based on mailcap entries.

When a bookmark is created using ‘C-x x c f’ or ‘C-x x c a’ for a file that matches ‘bmkp-default-handlers-for-file-types’, the shell command or Lisp function that “jumps to” (opens) the file is saved in the bookmark as property ‘file-handler’ (not ‘handler’).

Opening Bookmarks Using Windows File Associations

If you use Microsoft Windows there is no need to define new bookmark types and handlers, if the action you want is the one that Windows associates with the file. You already have a set of file/program associations, and Bookmark+ recognizes these as alternative handlers.

You can thus take advantage of Windows file associations to open bookmarks for files of all kinds. To do this, you also need library w32-browser.el. In the bookmark list, the following keys are bound to commands that open bookmarks using the associated Windows ‘Open’ applications:

Windows file associations are always available to you, in addition to any other file associations that you define using ‘bmkp-default-handlers-for-file-types’ (see Bookmarking Files You Cannot Visit with Emacs).

You can thus have two different programs associated with the same kind of file. Your MS Windows file association for PostScript might, for example, use Adobe Distiller to create a PDF file from PostScript, while your ‘bmkp-default-handlers-for-file-types’ association for Postcript might use GhostView to display it directly.

Besides using ‘M-RET’ etc. in buffer ‘*Bookmark List*’, if in ‘bmkp-default-handlers-for-file-types’ you register ‘w32-browser’ as the association to use for a given file pattern, then you can use command ‘bmkp-w32-browser-jump’ (not bound, by default) anywhere to open a bookmark whose file name matches that pattern, using its Windows file-association program.

You can also specify ‘w32-browser’ as the bookmark “type” when you use command ‘bmkp-jump-to-type’ (` C-x j :’). Either of these approaches gives you a way to use completion to choose a bookmark to open using a Windows file association.

Specifying such an association in ‘bmkp-default-handlers-for-file-types’ means that bookmarks for such a file will have a ‘file-handler’ value of ‘w32-browser’, to “jump” to (i.e., open) the file.

To set up a given file extension for use this way, add an entry (REGEXP . w32-browser) to option ‘bmkp-default-handlers-for-file-types’, where REGEXP matches the file extension.

For example, to make a command such as ‘bmkp-bookmark-a-file’ (‘C-x x c a’) automatically bookmark *` `.doc**’ files using the associated MS Windows program (typically MS Word), add this entry: ("\.doc$" . w32-browser)`.

Autofile Bookmarks

An autofile bookmark , or just an autofile , is a bookmark to a file or directory that uses the nondirectory part of its file name (or of its ‘directory-file-name’, if a directory name) as the bookmark name.

You can look at an autofile bookmark as just a wrapper around a file or directory: a way to attach meta information (such as tags) to it. But you can use an autofile bookmark much as you would use a file or directory.

To create a new autofile bookmark, you can use ‘bmkp-bookmark-a-file’ (aka ‘bmkp-autofile-set’), which is bound by default to ‘C-x x c a’. (In general, the key ‘a’ is used in key sequences for autofile bookmarks.)

If user option ‘bmkp-propertize-bookmark-names-flag’ is non-‘nil’, which it is by default with Emacs 21 and later, then you can have multiple bookmarks with the same name. This is important for autofile bookmarks because the bookmark name is only the nondirectory part of the file name. This Bookmark+ feature lets you have different autofile bookmarks for files of the same name in different directories.

In addition to the single autofile bookmark that you can create for a given absolute file location, you can of course create additional bookmarks to the same file or directory, using different bookmark names. Among other things, this lets you tag the same file or directory in different ways.

You can use ‘C-x j a’ (‘bmkp-autofile-jump’) or ‘C-x 4 j a’ (‘bmkp-autofile-jump-other-window’) to visit an autofile bookmark. And there are commands for visiting an autofile that is tagged in certain ways. For example, ‘bmkp-autofile-some-tags-regexp-jump’ (**` C-x j t a % +**’) jumps to an autofile bookmark that has at least one tag matching a given regexp. See Tagging Files.

You can create autofiles automatically whenever you use an Emacs file-cache command, by customizing user option ‘bmkp-autofile-filecache’.

This optional bookmark creation can replace adding the file to the cache, or it can be in addition to caching the file. This is done by advising command ‘file-cache-add-file’, which means that it affects also the other Emacs file-cache commands that use that function, directly or indirectly:

See FileNameCache and the Emacs manual, node `File Name Cache'.

If option ‘bmkp-autofile-access-invokes-bookmark-flag’ is non-‘nil’ then regular access of a file or directory (e.g. ‘find-file’) invokes the associated autofile bookmark, if there is one. This has the effect of updating the bookmark data, such as the number of visits. The default value of the option is ‘nil’. To set the option value, either use Customize interactively or use a Customize function.

Finally, if you use libraries Dired+ and Highlight (highlight.el) then autofiles are highlighted specially in Dired, and the highlighting indicates whether the file is tagged. Here is a screenshot:

DrewsEmacsDiredAutofiles

A Type-Aware `find-file'

User option ‘bmkp-default-handlers-for-file-types’ (see Bookmarking Files That You Cannot Visit with Emacs") gives you a way to associate a file type, as determined by the file name (typically its extension) with a default file action. This is like MS Windows file associations, but it is specific to Emacs and Bookmark+. And it is useful for more than just bookmarks.

Commands ‘bmkp-find-file’ (‘C-x j C-f’) and ‘bmkp-find-file-other-window’ (‘C-x 4 j C-f’) take advantage of this association to open files. If a file name matches no pattern in ‘bmkp-default-handlers-for-file-types’ then these commands act like ‘find-file’ and ‘find-file-other-window’. Otherwise, the invoke the associated file handler in ‘bmkp-default-handlers-for-file-types’.

Invoking the handler is just what the ordinary autofile jump commands (e.g. ‘C-x j a’) do. But ‘bmkp-find-file’ is different in a couple of ways.

Like vanilla ‘find-file’ (‘C-x C-f’), ‘C-x j C-f’ and ‘C-x 4 j C-f’ use ‘read-file-name’ to prompt you for the file name. The completion candidates are the names of all of the files in the current directory (‘default-directory’), that is, the directory of your current minibuffer input. This includes the names of any autofile bookmarks in the same directory. And like ‘C-x C-f’ you can change directory, navigating up and down the file hierarchy. In sum, these commands are file-aware.

The ordinary autofile jump commands on the other hand use ‘completing-read’ to complete your input against all autofile bookmark names, regardless of directory. And since the bookmark names reflect only the relative file names, it is not so easy to distinguish two autofiles with the same name but in different directories. (Icicles can help here, BTW.)

There is a ‘bmkp-find-file-’ command that corresponds to each ‘bmkp-autofile-’ command. For example, ‘bmkp-find-file-some-tags-regexp’ (`C-x j t C-f % +’) corresponds to ‘bmkp-autofile-some-tags-regexp-jump’ (`C-x j t a % +’). All ‘bmkp-find-file’ commands use `C-f**’ in their key bindings, as a reminder of their reading file names a la **‘find-file’.

But whereas ‘C-x j C-f’ and ‘C-x 4 j C-f’ let you access any file, the other ‘bmkp-find-file-’ commands, which find files that have certain tags, provide only autofiles as completion candidates. That’s obvious, since files are tagged by bookmarking them.

You can thus use the ‘C-f’ commands to take advantage of file-action associations that you define. But if you want to associate metadata (e.g. tags) with files or directories, then you will want to create autofiles. You can do this when you invoke these commands, by providing a prefix argument. Thus, for example, ` C-u C-x j C-f foo.doc’ opens file ` foo.doc’, respecting any handler recorded for it via option ‘bmkp-default-handlers-for-file-types’ – but it also creates an autofile bookmark for it.

Whenever an autofile bookmark is used, regardless of whether you access it using a ‘bmkp-autofile*’ command or a ‘bmkp-find-file*’ command, the full bookmark record (including handler) is taken into account.

Note, however, that the ‘C-f’ tag commands differ from the ‘a’ tag commands in how the completion candidates are filtered.

For the former, ‘read-file-name’ is passed a predicate that is applied to each file name in the directory, filtering out any such candidates that do not satisfy it (e.g., do not have the required tags).

This happens before you type any input to match the file name. The predicate checks for a corresponding autofile and checks its tags (depending on the command). If there are lots of files in the current directory, this can take a while.

For the latter, similar tests are made, but instead of testing each file in the current directory, these commands test each bookmark in the current bookmark list. If there are lots of bookmarks this can take a while.

In some cases a ‘C-f’ command is quicker; in some cases a ‘a’ command is quicker.

If you use Icicles, then the performance hit for ‘C-f’ when there are lots of files in a directory is greatly reduced. This is because Icicles applies the filtering predicate after, not before, you type text in the minibuffer. In other words, instead of testing each file in the directory, it tests only the files that match your input. (In addition, if you use Icicles then you get multi-command versions of each of these bookmark commands, which means that you can visit more than one file per command invocation.)

Tagging Files

Section Tags: Sets of Bookmarks covers bookmark tags, which are persistent metadata that you define to help you organize bookmarks into meaningful sets.

Section Autofile Bookmarks describes autofile bookmarks, which, in effect, let you treat files and directories generally as if they were bookmarks. You can choose a file or directory to visit or act on by its name and location, but also by its bookmark metadata.

In particular, you can tag a file or directory – that is, specify tags for its associated autofile bookmark. And you can then visit a file or directory that has a given set of tags. Bookmark+ provides file commands that automatically create and manipulate autofile bookmarks, that is, bookmarks that have the same name as the files or directories they tag.

Command ‘bmkp-tag-a-file’ (aka ‘bmkp-autofile-add-tags’), bound by default to ` C-x x t + a**’, prompts you for a set of tags and a file or directory, and creates or sets the corresponding autofile bookmark. Command **‘bmkp-untag-a-file’** (aka **‘bmkp-autofile-remove-tags’**), bound by default to **‘C-x x t - a’, similarly lets you remove specified tags from a file or directory.

If you also use library Icicles, then you can act on multiple files and directories during the same command (a multi-command). You can thus all at once tag a set of files and directories the same way, or act on a set of files and directories that are tagged similarly. Icicles also lets you create autofiles or add or remove tags, on the fly, whenever you use commands (e.g. ‘C-x C-f’) that access files or directories.

If you also use library Dired+ (dired+.el) then you can use **` C-+**’ to add tags to the marked files and directories, and **‘C--’** to remove tags from them. You can use **` C-M-+**’ and ‘C-M--’ to do the same thing for the current file. You can also use items from the Dired menus to do these things.

Bookmark+ provides two kinds of command for visiting files associated with bookmarks that have tags.

The first kind uses bookmarks directly: you choose a bookmark name, not a file name, but the candidates are only file and directory bookmarks. These commands have the prefix ‘bmkp-file-’ or ‘bmkp-autofile-’.

As a special case, commands with the prefix ‘bmkp-file-this-dir-’ limit the choices to bookmarks for files and subdirectories of the current directory. By default, the commands across all directories are on prefix key ‘C-x j t f’, and those for the current directory only are on prefix key **` C-x j t .**’. See Different Types of Jump Commands for more about these commands.

The second kind of command is for visiting tagged files, that is, autofile bookmarksjust like the commands with prefix ‘bmkp-autofile-’. However, these commands do not handle the bookmark as such, but only its associated file or directory. They recognize its tags, but they pay no attention to any special handler or other recorded information.

These commands have the prefix ‘bmkp-find-file-’, and they are on the prefix key ‘C-x j t C-f’. The ‘C-f’ here is intended to remind you of command ‘find-file’ (‘C-x C-f’). Like ‘find-file’, they use ‘read-file-name’ to read the bookmark’s file name, instead of using ‘completing-read’ to read the bookmark name.

Yes, for an autofile bookmark the bookmark name and the relative file name are the same. But ‘read-file-name’ is file-aware, and lets you browse up and down the directory hierarchy.

The ‘bmkp-find-file-’ commands are available only for Emacs 22 and later (because they use ‘read-file-name’ with a PREDICATE argument).

For example:

`C-x j t f % +’ is ‘bmkp-file-some-tags-regexp-jump’

`C-x j t . % +’ is ‘bmkp-file-this-dir-some-tags-regexp-jump’

`C-x j t a % +’ is ‘bmkp-autofile-some-tags-regexp-jump’

`C-x j t C-f % +’ is ‘bmkp-find-file-some-tags-regexp’

If you use Icicles, there are similar sets of commands, but they all let you act on multiple files and directories at the same time (multi-commands). For example, you can delete (or byte-compile or…) a set of files and directories according to their tags.

Remember that you can create multiple bookmarks for the same file or directory, providing them with different sets of tags. (Only one of the bookmarks is the autofile bookmark.)

You can also use multiple bookmark files (the files that record bookmarks). Different projects can thus have different tags for the same sets of files and directories, even using just autofile bookmarks. See Using Multiple Bookmark Files.

A file or directory bookmark can have any number of tags, and multiple file bookmarks can have the same tag. You can sort, show/hide, or mark files and directories based on their tags.

Using Multiple Bookmark Files

Bookmark-list views provide one way to switch among various sets of bookmarks that you use. But that feature affects only the bookmarks that you see displayed in buffer ‘*Bookmark List*’, not the actual set of available bookmarks.

The bookmarks available to you are defined in a bookmark file. By default, they are stored in the file named by option ‘bmkp-last-as-first-bookmark-file’, if non-‘nil’, otherwise in the file named by option ‘bookmark-default-file’ (` ~/.emacs.bmk’, by default).

If you use only one bookmark file then you never need to load or save it manually. Emacs does that for you automatically.

But you can have multiple bookmark files if you want, and at any time you can change the bookmark file that is current. To do that, use ‘C-x x L’ (or just ‘L’ in the bookmark-list display), which is bound to command ‘bmkp-switch-bookmark-file-create’. Having multiple bookmark files gives you an added degree of flexibility.

By default, the last bookmark file you used, in your last Emacs session, is the initial bookmark file that is loaded automatically in your next session. But if you prefer, you can make Bookmark+ always start with the same bookmark file (‘bookmark-default-file’). User option ‘bmkp-last-as-first-bookmark-file’ controls this.

You can easily see which bookmark file is current at any time: It is shown at the top of buffer ‘*Bookmark List*’, and it is near the top of the help output from command ‘bmkp-bmenu-mode-status-help’, which is what is bound to ` ?’ and ‘C-h m’ in buffer ‘*Bookmark List*’.

When you switch to another bookmark file, the default choice for the file to switch to is the last bookmark file you used (in the same session). So it is trivial to toggle back and forth between two bookmark files: just hit ‘RET’ to accept the default.

When bookmarks are saved automatically, or when you save them using ‘bookmark-save’ (‘S’ in the bookmark-list display or ‘C-x x s’ globally) and you don’t use a prefix argument, they are saved in the current bookmark file.

You can turn off the automatic saving of the current bookmark file, by customizing option ‘bookmark-save-flag’ to ‘nil’. And you can toggle this option at any time, using ` M-~**’ in the bookmark list (command **‘bmkp-toggle-saving-bookmark-file’).

Besides using multiple bookmark files as alternatives, you can combine them, using them as component bookmark subsets (like modules). To do that, use command ‘C-x x l’ (lowercase ‘l’), which is bound to ‘bookmark-load’, and do not use a prefix argument. (Using a prefix argument with ‘C-x x l’ is the same as using ‘C-x x L’: it switches bookmark files.) Here too the default is the name of the last bookmark file that you used.

In the ‘*Bookmark List*’ display you can use ‘M-l’ to load all of the bookmark files corresponding to the marked bookmark-file bookmarks, in the order in which they are displayed. Any non bookmark-file bookmarks that are marked are ignored. Before loading, if any of your currently loaded bookmarks have been modified then you are asked if you want to save them first, before loading the others.

After loading, to avoid confusion and possible mistakes, automatic saving to the current bookmark file is turned off. You can always use ` M-~’ to turn it back on again. And remember that, as long as you have not saved bookmarks after loading, you can always use ‘C-u g’ to revert to the bookmarks saved in the bookmark file.

To create additional bookmark files, to use either as alternatives or as components, you can either copy an existing bookmark file or use ‘bmkp-empty-file’ (‘C-x x 0’) to create a new, empty bookmark file. If you use ‘C-x x 0’ with an existing bookmark file, then its bookmarks are all deleted – it is emptied.

Instead of simply copying a bookmark file, you can use ‘bookmark-save’ with a prefix argument, or use ‘bookmark-write’ (bound to ‘C-x x w’), to save the currently defined bookmarks to a different bookmark file.

However a bookmark file was created, you can switch to it and then add or delete bookmarks selectively, to change its content. Remember too that you can delete bookmarks from the current set using command ‘bookmark-delete’ (‘C-x x d’) or, in the bookmark list, using ‘d’ plus ‘x’ or marking then ‘D’.

Deleting bookmarks from a bookmark file is one way of editing it. Another is to copy or move bookmarks from one bookmark file to another. In the bookmark-list display, you can copy or move the marked bookmarks (or the current bookmark, if none are marked) from the current bookmark file to another that you name, using **`Y > +**’ (‘bmkp-bmenu-copy-marked-to-bookmark-file’) and **` Y > -**’ (‘bmkp-bmenu-move-marked-to-bookmark-file’), respectively. And you can use **` Y > 0**’ (‘bmkp-bmenu-create-bookmark-file-from-marked’) to create a new bookmark file by copying the marked bookmarks. With a prefix argument, ` Y > 0’ creates also a bookmark-file bookmark.

In any location (any file or any buffer that can be bookmarked), you can switch to a bookmark file that has only bookmarks for the current file or buffer, creating such a file on the fly if none exists. To do this, use ‘C-x x C-l’ (‘bmkp-switch-to-bookmark-file-this-file/buffer’).

NOTE:

Unlike the other ways of organizing bookmarks into sets (tags, bookmark-list bookmarks, etc.) bookmark files represent physical, not logical, groupings of bookmarks. A bookmark file contains complete bookmark records.

If you copy a bookmark from one bookmark file to another, the copy is an independent bookmark: it has no relation to the bookmark it was copied from. Changes to the copy or the bookmark it was copied from do not affect each other.

This means that to use bookmark files for organizing bookmarks you will typically move, not copy, bookmarks between them (or copy and later delete). Remember that you can load multiple bookmark files to access their bookmarks together in a session. Think of your bookmark files as independent modules that you can combine.

See Also: Bookmark+ Load Order and Option `bookmark-default-file'.

Bookmark Files For Bookmarks with Specific Tags

Bookmark+ provides various features for creating, manipulating, and making use of bookmarks, but it generally doesn’t provide predefined ways to use such features together to accomplish a particular goal.

This includes uses of features to organize bookmarks and their destinations or results/effects. But here’s an example of using a couple features out of the box to do that: create a bookmark file for bookmarks with a given set of tags.

You can have multiple bookmark files, which you can use separately or in combination. If you use tags as a way of “categorizing” bookmarks then you might create one or more bookmark files for bookmarks tagged in particular ways. For example, have a bookmark file that contains only bookmarks tagged both ‘travel’ and ‘2024’.

Loading that file alone gives you access to just those bookmarks, simplifying bookmark commands (jump, tag, filter, edit,…). Loading it together with another bookmark file, for example one for bookmarks with another set of tags, gives you access to both sets.

Here’s one way to create a bookmark file for bookmarks tagged in a particular way, using the bookmark-list display for a set of bookmarks that includes those bookmarks but also others: mark the bookmarks you want, then create a bookmark file from the marked bookmarks.

1. Unmark all bookmarks, using ‘U’ (or `M-DEL`).

2. Mark the bookmarks that have the tags you’re interested in.

You can do this using tags-command keys that mark according to their tags. These keys all begin with prefix key ‘T m’. For example, to mark bookmarks that are tagged with both ‘travel’ and ‘2024’ you can use ‘T m *’ and enter ‘travel’ and ‘2024’ when prompted (end with an empty ‘RET’).

Or if you want bookmarks with either ‘travel’ or ‘2024’ (or both), use ` T m +’. Another way to do this is to use ` T m %’ and enter the regexp ` \(travel\|2024\)’.

(Marking and unmarking commands are also in menu Bookmark+ > Mark.)

3. Copy the marked bookmarks to a new bookmark file.

Use ` Y > 0’ to do this, entering the file name at the prompt.

Or if you want to move the bookmarks instead of copying them (i.e., remove them from the current bookmark file), use ` Y > -’.

(Bookmark-file commands are also in menu Bookmark+ > Bookmark File.)

See Also: Tag Commands And Keys.

Bookmark-File Bookmarks

A bookmark file is an excellent, persistent way to represent a set of bookmarks. In particular, it can represent a project or a project component. Switch among bookmark files to access different projects. Load project components as you need them.

You can load a bookmark file using ‘C-x x L’ (switch) or ‘C-x x l’ (accumulate). As a convenience, you can also load a bookmark file by jumping to a bookmark-file bookmark.

You use command ‘bmkp-set-bookmark-file-bookmark’, bound to ‘C-x x y’, to create a bookmark-file bookmark. Jumping to such a bookmark just loads the bookmark file that it records. With ‘C-u’ (e.g. ‘C-u C-x j y project-foo’), jumping switches bookmark files. Without ‘C-u’ it accumulates the loaded bookmarks.

You can also use commands ‘bmkp-bookmark-file-load-jump’ and ‘bmkp-bookmark-file-switch-jump’ (unbound by default), which load and switch without prompting you for confirmation or whether to first save the current bookmark file.

A bookmark-file bookmark is not only an added convenience. You can also use it in combination with other Bookmark+ features, such as tagging.

As a shortcut, in Dired (if you use library Dired+), ‘C-M-b’ creates a bookmark-file bookmark. The bookmark file that it records contains autofile bookmarks to each of the files and subdirectories that was marked in Dired at the time it was created. Jumping to that bookmark-file bookmark makes those (marked) files and subdirectories available as bookmarks. See also Use Dired to Bookmark Files without Visiting Them.

Note that the bookmark file in which a bookmark-file bookmark is recorded is not the same as the bookmark file recorded in that bookmark.

For example, when you use ‘C-M-b’ in Dired, the bookmark-file for the marked files is, by default, file ` .emacs.bmk’ in the Dired directory. So if you are in directory ‘/foo/bar’ the default bookmark file for the marked files is ` /foo/bar/.emacs.bmk’. But the new bookmark-file bookmark created is recorded in the current bookmark file, whatever that might be (e.g. ` ~/.emacs.bmk’).

The Bookmark List Display

Bookmark+ enhances the bookmark list (aka the bookmark “menu list”, a misnomer) that is displayed in buffer ‘*Bookmark List*’ when you use ‘C-x x e’ or ‘C-x r l’ (command ‘bookmark-bmenu-list’).

At the top of the bookmark-list display is this header information:

For example, this header indicates that the current bookmark file is c:/.emacs.bmk and only file and directory bookmarks are shown:

Bookmark file: c:/.emacs.bmk

File and Directory Bookmarks

(Bookmark+ does not use the sliding header line of vanilla Emacs 24+, which means that option ‘bookmark-bmenu-use-header-line’ has no effect. You do not need to see ‘Bookmark’ and ‘File’ column headers as you scroll.)

Bookmarks are highlighted to indicate their type. You can mark and unmark bookmarks, show or hide bookmarks of particular types, and more. Bookmarks that have tags are marked with a ‘t’. Bookmarks that have an annotation are marked with an ‘a’ (not with a ‘*’ as in vanilla bookmark.el). Bookmarks that have been modified since the last save of the bookmark file are marked with a ‘*’. Bookmarks that have bookmark-highlight override settings (see DefiningHowtoHighlight) are marked with a one-character pink background.

Use ` ?’ or ‘C-h m’ in buffer ‘*Bookmark List*’ for more information about the bookmark list, including the following:

Jumping To Bookmarks from the Bookmark List Display

Bookmark visiting (jumping) commands are globally on prefix keys ‘C-x j’ and ‘C-x 4 j’. In the bookmark-list display they are additionally on ‘j’ (other window) and ‘J’ (same window). In addition, ` j >**’ is bound to **‘bmkp-bmenu-jump-to-marked’, which jumps to each of the marked bookmarks in other windows.

Tag Commands and Keys

There are lots of tag-related bookmark commands, and most are bound to keys in buffer ‘*Bookmark List*’ as well as to other keys outside it. How can you keep the commands straight or remember their keys?

In the bookmark list display, tags-command keys begin with prefix key ‘T’. Elsewhere, they begin with prefix key ‘C-x x t’ (or ‘C-x j t’, for jump commands – see Different Types of Jump Commands).

‘C-h m’ is your friend, of course. Likewise ‘T C-h’, ‘C-x x t C-h’, and **` C-h >**’ (which describes the marked bookmarks). Beyond that, the tag-related keys that are more than two keystrokes are organized as follows:

The key ‘T m *’, for instance, marks (‘m’) the bookmarks that are tagged with all (‘*’ = AND) of a given set of tags. It prompts you for one or more tags that the bookmarks must have, and it marks all bookmarks that have all of the tags you enter.

The key ` T u ~ +’ unmarks (‘u’) the bookmarks that do _not_ (` ~’) have any (` +’ = OR) of the tags you specify. And so on. The marking and unmarking commands for tags compare the tags a bookmark has with tags that you enter. Any bookmarks that have no tags are ignored – they are neither marked nor unmarked by these commands.

**` +**’ and **‘-’** can also mean _add_ and _remove_ tags, respectively, and **` >**’ stands for the marked bookmarks. So ` T > +’ adds (` +’) one or more tags to each of the marked (` >’) bookmarks.

In general, the tag-related commands let you enter a set of tags, one at a time. Thus, instead of having a command that adds a single tag to the current bookmark, you have a command that adds any number of tags to it. To add just a single tag, hit ‘RET’ twice: once to enter the tag, and once again to indicate that it is the last (i.e., the only) one.

If you just hit ‘RET’ immediately, specifying an empty set of tags, then each of the commands does something appropriate. For ‘T m *’, for instance, an empty list of tags means to mark (only) the bookmarks that have some tags (any at all).

Finally, for the marking/unmarking tags commands, a prefix argument flips the sense of the command, in this way:

In other words:

C-u T m * = T m ~ + (all are NOT = not some are) C-u T m ~ + = T m * (not some are NOT = all are) C-u T m + = T m ~ * (some are NOT = not all are) C-u T m ~ * = T m + (not all are NOT = some are)

You’ll figure it out ;-).

Other important keys pertaining to tags (the keys in parentheses work in any buffer, not just buffer ‘*Bookmark List*’):

In the bookmark list display you can also sort bookmarks according to how they are tagged, even in complex ways. See SortingBookmarks.

Tags: Sets of Bookmarks

The best way to think about tags is as names of persistent sets. All bookmarks tagged ‘blue’ constitute the bookmark set named ‘blue’. The bookmarks visible in the bookmark list at any time also constitute an unnamed set. Likewise, the marked bookmarks and the unmarked bookmarks are unnamed sets. Bookmark+ is all about helping you act on sets of Emacs objects. Bookmarks are named, persistent pointers to objects such as files and file sets. Bookmark tags are named, persistent sets of bookmarks (and hence of their target objects).

The marking commands make it easy to combine sets as unions or intersections. And you can give the result a name for quick access later, just by adding a new tag. In other words, do the set-definition work only once, and name the result.

How would you tag as ‘Java IDE Projects’ the bookmarks that are already tagged both ‘Java’ and ‘ide’?

  1. ‘T m * Java RET ide RET RET’, to mark them.
  2. ` T > + Java IDE Projects RET RET, to tag them.

How would you sort your bookmarks, to show all those tagged both ‘blue’ and ‘moon’ first?

  1. ‘T m * blue RET moon RET RET’, to mark them.
  2. ` s >’ to sort the marked bookmarks first (see SortingBookmarks, below).

If you wanted to show only the marked bookmarks, instead of sorting to put them first in the list, you would use ` >’ instead of ` s >’.

How would you query-replace the set of files that are tagged with any of the tags ‘alpha’, ‘beta’, and ‘gamma’, but are not tagged ‘blue’ or ‘moon’?

  1. ‘F S’, to show only the file bookmarks (see FilteringBookmarks, below).
  2. ` T m + alpha RET beta RET gamma RET RET’, to mark the bookmarks that have at least one of those tags.
  3. ` T u + blue RET moon RET RET’, to unmark those that are tagged ‘blue’ or ‘moon’.
  4. ‘M-q’ to query-replace the marked files.

If that were a set of files that you used often, then you would name the set by giving the files a new tag.

The point is that bookmarks, and bookmark tags in particular, let you define and manipulate sets of Emacs objects. It doesn’t matter how you define such a set: regexp matching (marking, filtering), by object type, by tag combinations… Sets need not be named to act on them, but you can provide them with persistent names (tags) to avoid redefining them over and over. Manipulation of bookmarked objects includes visiting, searching, and query-replacing. And you can define your own bookmark types (using bookmark handlers) and associated manipulations.

Open Dired for the Marked File Bookmarks

You’ve seen that the bookmark list has many features that are similar to Dired features. But Dired is specialized for files and directories, and it has many more features for manipulating them. The bookmark list is not intended to replace Dired.

You can, however, use the bookmark list to take advantage of arbitrary Dired features for file and directory bookmarks. Command ‘bmkp-bmenu-dired-marked’ (**` M-d >**’) weds **Bookmark+**’s set-defining and set-manipulating features (tagging, marking, filtering etc.) to Dired’s file-manipulating features.

` M-d >’ opens a Dired buffer that is specialized for just the files and directories whose bookmarks are marked in the bookmark list. (Other marked bookmarks are ignored by the command.) The files and directories can be located anywhere; they need not be in the same directory. They are listed in Dired using absolute file names.

(In Emacs versions prior to release 23.2, only local files and directories can be handled, due to Emacs bug #5478. In such versions, remote-file bookmarks are ignored by ` M-d >’.)

This Bookmark+ feature makes sets of files and directories immediately amenable to all of the operations provided by Dired.

It is particularly useful in conjunction with tags. Use bookmark tags and marks to define a possibly complex set of file and directory bookmarks. Then hit ` M-d >’ to list them in a Dired buffer. Then use any Dired commands you want to act on any of them.

For example, to compress bookmarked files that are tagged with both ‘blue’ and ‘moon’:

  1. Mark them using ‘T m * blue RET moon RET RET’.
  2. Open Dired for them using ` M-d >’.
  3. Mark them in Dired, then compress them using ‘Z’.

Since tags are persistent, Bookmark+ gives you a good way to define an arbitrary set of files as a project and then open them in Dired at any time to operate on them.

If you use Dired+ (library dired+.el), then a similar feature is available for the marked files and directories: You can use ‘C-M-*’ in Dired to open a separate Dired buffer for them only. You can of course then bookmark that resulting Dired buffer, if you like.

If you use Icicles, then whenever you use a command that reads a file (or directory) name, you can use **` M-|**’ during file-name completion to open Dired on the currently matching set of file names. That is, this is the same kind of special Dired buffer that is provided for file and directory bookmarks by ` M-d >’ in the bookmark list.

Marking and Unmarking Bookmarks

Bookmark+ enhances marking and unmarking of bookmarks in the bookmark list in several ways. In general, these enhancements are similar to features offered by Dired and Dired X. You can use:

Filtering Bookmarks (Hiding and Showing)

There are three ways to show only certain bookmarks.

1. Filter by bookmark type.

2. Filter bookmarks incrementally and temporarily, using pattern matching.

3. Filter out the marked or unmarked bookmarks.

Filtering by bookmark type

The commands that show only bookmarks of a particular type are bound to keys that end in ‘S’ (for “show”). For example, ‘I S’ shows only Info bookmarks, and ‘X S’ shows only temporary bookmarks.

The type filter is reflected in the bookmark-list display title. It says ‘All Bookmarks’ if no type filter is used. Otherwise it tells you what kind of bookmarks are listed: ‘Autonamed Bookmarks’, ‘File and Directory Bookmarks’, and so on.

Note: It is only filtering by bookmark type that is remembered when you save a bookmark-list display state or you create a bookmark-list bookmark. See State-Restoring Commands and Bookmarks.

Filtering incrementally by pattern matching

These commands show only bookmarks that in some way match a pattern (regexp) that you type. The bookmarks are filtered incrementally as you type the pattern. Hit any non-inserting key, such as ‘RET’, to finish defining the pattern.

The commands for this are bound to keys that start with ‘P’ (for “pattern”). For example, ‘P B’ shows only bookmarks whose names match the regexp, ‘P F’ shows those whose file names match, ‘P A’ shows those whose annotations match, and ‘P T’ shows those that have one or more tags that match. (See BookmarkTags, above, for information about tags.)

Filtering based on marking

Just as in Dired, you can use **` % m**’ to mark the bookmarks that match a regexp. Then use **` >**’ to show only the marked bookmarks. See MarkingAndUnmarkingBookmarks, above.

This method has the advantage that you can show the complement: the bookmarks that do not match the regexp, by using **` <**’ instead of ` >’. It also has the advantage that matching checks the combination of bookmark name and file name (use ‘M-t’ to toggle showing file names).

These are the keys for hiding or showing bookmarks:

Only Visible Bookmarks Are Affected

Commands that operate on the current bookmark or on the marked or the unmarked bookmarks act only on bookmarks that are displayed (not hidden). This includes the commands that mark or unmark bookmarks. This means that you can easily define any given set of bookmarks.

For example:

  1. ‘F S’ – _S_how only bookmarks associated with _f_iles.
  2. ` % m’ – _M_ark those whose names match a particular regexp.
  3. ‘R S’ – _S_how only bookmarks that have _r_egions.
  4. ‘m’ – _M_ark some of those region bookmarks individually.
  5. ` .’ – Show all bookmarks.
  6. ‘t’ – _T_oggle the marked and unmarked (so unmarked are now marked)
  7. ‘D’ – _D_elete all of the marked bookmarks (after confirming)

Together, steps 1-7 delete all file bookmarks that match the regexp and all region bookmarks that you selectively marked.

Omitting Bookmarks from Display

In sections MarkingAndUnmarkingBookmarks and FilteringBookmarks you learned how to hide and show bookmarks in the bookmark list. This section is about a different kind of hiding, called omitting.

Omitted bookmarks are not shown in the bookmark list, no matter what filtering is used. The only way to show omitted bookmarks is to show all of them and only them, using ‘- S’, which is bound to command ‘bmkp-bmenu-show-only-omitted’.

Omitted bookmarks are still available even if they are not shown, and you can still jump to them (e.g. using ‘C-x r b’). You just don’t see them in the bookmark list. And that’s the reason for this feature: to hide those bookmarks that you don’t care to see.

One use for this feature is to hide the component bookmarks that make up a sequence bookmark (see FunctionSequenceVarlistBookmarks). The default behavior when you create a sequence bookmark is in fact to omit its component bookmarks from the displayed list.

You can omit any bookmarks by marking them and then using **` - >**’ (**‘bmkp-bmenu-omit/unomit-marked’**). If you are looking at the omitted bookmarks (after using ‘- S’), then ` - >’ **un**-omits the bookmarks marked there. Think of two complementary spaces: the normal bookmark list and the omitted bookmark list. When you use ` - >’, the marked bookmarks that are currently shown are moved to the opposite space.

You can un-omit all of the omitted bookmarks at once, using ‘- U’ (‘bmkp-unomit-all’). You can also call this command from outside the bookmark-list display.

Omitted bookmarks that are marked are generally not included when you use a command that acts on the marked bookmarks. However, if you use a negative prefix argument with the command then they are.

For some commands this is relaxed so that any prefix arg has this effect. For other commands a non-negative prefix arg has a different effect. In some cases, a non-negative prefix arg has one effect and a non-positive prefix arg has the effect of including omitted marked bookmarks, so that a zero prefix arg has both effects. For any given command, consult the doc string for full information.

Sorting Bookmarks

Filtering hides certain kinds of bookmarks. Sometimes, you want to see bookmarks of various kinds, but you want them to be grouped or sorted in different ways, for easy recognition, comparison, and access.

Bookmarks shown in the bookmark list are sorted using the current value of option ‘bmkp-sort-comparer’. (If that is ‘nil’, they are unsorted, which means they appear in reverse chronological order of their creation.)

You can use **‘s s’**… (repeat hitting the ‘s’ key) to cycle among the various sort orders possible, updating the display accordingly. By default, you cycle among all available sort orders, but you can shorten the cycling list by customizing option ‘bmkp-sort-orders-for-cycling-alist’.

You can also change directly to one of the main sort orders (without cycling) using **` s >**’, **‘s n’**, **‘s f n’**, etc. There are many such predefined sort orders bound to keys with the prefix ‘s’ — use ‘C-h m’ or ` ?’ for more info.

You can _r_everse the current sort direction (ascending/descending) using ‘s r’. Also, repeating any of the main sort-order commands (e.g. ‘s n’) cycles among that order, the reverse, and unsorted.

[For a complex sort, which involves composing several sorting conditions, you can also use ‘s C-r’ to reverse the order of bookmark sorting groups or the order within each group (depending on whether ‘s r’ is also used). Try it, for example, together with sorting by bookmark kind (‘s k’).

Be aware that ‘s C-r’ can be a bit unintuitive. If it does not do what you expect or want, or if it confuses you, then don’t use it ;-). (‘s C-r’ has no noticeable effect on simple sorting.)]

Remember that you can combine sorting with filtering different sets of bookmarks – bookmarks of different kinds (e.g. Info) or bookmarks that are marked or unmarked.

Finally, you can easily define your own sorting commands and sort orders. See macro ‘bmkp-define-sort-command’ and the documentation for option ‘bmkp-sort-comparer’. (Bookmark+ uses option ‘bmkp-sort-comparer’; it ignores vanilla Emacs option ‘bookmark-sort-flag’.)

Of particular note is that you can interactively define commands that sort by a given list of tags — you use keys ‘T s’ (command ‘bmkp-define-tags-sort-command’) to do that. You are prompted for the tags to sort by. Bookmarks are sorted first according to whether they are tagged with the first tag, then the second tag, and so on. Otherwise, sorting is by bookmark name.

The tags you specify are used, in order, in the name of the new command. For example, if you enter tags ‘alpha’, ‘beta’, and ‘gamma’, in that order, then the sorting command created is ‘bmkp-bmenu-sort-alpha-beta-gamma’. The new command is saved in your bookmark commands file (‘bmkp-bmenu-commands-file’).

Note that because you can add a new tag to all bookmarks that have some given set of tags, you can use that single (new) tag to represent the entire tag set. Sorting by that tag is then the same as sorting by the tag set. You can of course use overlapping sets in the composite sort command. You can, for example, sort first according to tag ‘tag1’, which represents the set of tags ‘alpha’, ‘beta’, ‘gamma’, ‘delta’, and then sort according to tag ‘tag2’, which represents the set of tags ‘beta’, ‘delta’.

See also ApplesAndOranges for more about the sorting used in Bookmark+. See also bookmark sorting in Icicles – the same technique is used in Icicles for sorting bookmarks as completion candidates.

Bookmarks for Specific Files or Buffers

A bookmark typically records a position or a region in a file or buffer. Sometimes you are interested in accessing or examining only the bookmarks for particular files or buffers. For example, you might want to navigate among the bookmarks for the current buffer. Or you might want to search the regions recorded in the bookmarks for a particular file.

For a bookmark, the recorded file and buffer name differ in that the file name is absolute. Bookmarks for buffer ` foo.el’ include all files named ` foo.el’, whereas bookmarks for file ` /project1/lisp/foo.el’ include only the files in that one directory.

Another important difference is that when multiple buffers visit different files that have the same relative file name (i.e., in different directories), Emacs makes the buffer names unique by appending ` <N>’ as needed, where ‘N’ is 2, 3,… When you create a bookmark, the current buffer name is recorded as the bookmark’s buffer. If the current buffer is not visiting a file, then the bookmark created is a non-file bookmark. In that case, to use the bookmark later you must have a buffer of the same name (e.g. ` foo.el<2>’).

Bookmark+ provides commands to handle these different use cases: specific files and specific buffers. The keys bound to these commands use ‘f’ for file and ‘b’ for buffer. In the bookmark-list display, the following keys affect the bookmarks for a particular file or buffer whose name you provide (with completion).

For navigation, the following keys jump to bookmarks for particular files or buffers. (Use ‘C-x 4 j’ for other-window.)

For the `=’ keys you are prompted for one or more file names or buffer names.

Finally, because the bookmarks in the current buffer can be of particular interest, **` C-x x ,**’ opens the bookmark-list display for only those bookmarks. (**` ,**’ stands generally for “this-buffer” in Bookmark+ key bindings.)

Cycling, Navigation List

Using completion to jump to a bookmark is handy. It lets you choose a bookmark by its name and gives you direct (“random”) access to it.

Sometimes, however, you don’t much care what a bookmark is named, and you want to cycle quickly among relatively few, related bookmarks. Obviously, the smaller the number of bookmarks in the set, the more convenient cycling is – with many bookmarks cycling can become tedious.

An analogy: If your TV has lots of channels, then the channel up/down buttons on the remote control are not so useful: 32, 33, 34, …, 79! Unless the channel you want happens to be near the current channel, cycling around a huge ring of channels is not the way to go. And just because your TV receives lots of channels does not mean that you watch them all or that you are equally interested in them all.

Some TV remote controls have a feature that mitigates this problem. You can define a ring of favorite channels, and there are two additional buttons that let you cycle forward and backward around the ring, skipping the channels in between. The number of favorites is relatively small, so cycling is not tedious. More importantly, all of the channels in the ring are ones you are interested in.

Extend this idea to allow for assigning different sets of channels to the favorites ring at different times: choose the ring you want at any time: sports, music, films, science, art, history, and so on. Add the possibility of sorting those sets in various ways, to further facilitate cycling, and you arrive at the idea behind the Bookmark+ navigation list.

Another analogy is a music playlist. You can use Bookmark+ as a simple music player by bookmarking music files. Similarly, you can use Bookmark+ to create slideshows by bookmarking image files. Cycle the navigation list to move through the slide show.

If you use MS Windows, you can take advantage of your existing file associations to open your bookmarks using the appropriate program – no need to define a new bookmark type and handler. See Bookmarking Files That You Cannot Visit with Emacs.

Note: The default value of option ‘bmkp-use-region’ is ‘t’, not ‘cycling-too’, which means that when you cycle to a bookmark its recorded region (if any) is not activated. This is probably what you want most of the time. Cycling is a repetitive action, and if you cycle to a bookmark with no recorded region then an already active region is just extended. Customize the value to ‘cycling-too’ if you prefer that behavior.

The Bookmark Navigation List

Bookmark+ is all about letting you define and manipulate sets of bookmarks. When a bookmark set can be used for cycling (as well as jumping) it is called the navigation list or navlist, for short.

In other words, Bookmark+ lets you cycle among any set of bookmarks. When you cycle, it is the set that currently constitutes the navigation list that is cycled.

Here are two ways to define the navigation list:

Each of these lets you choose a set of bookmarks using completion. For ` C-x x :’ you are prompted for the type of bookmark (e.g. ‘dired’).

For ‘C-x x B’ you are prompted for the name of a bookmark-list bookmark that you created. But you can also choose the candidate ‘CURRENT *Bookmark List*’ to capture the bookmarks that would be shown currently in the ‘*Bookmark List*’ (even if the list is not displayed now). See State-Restoring Commands and Bookmarks for information about bookmark-list bookmarks.

If you do not define the navigation list before you start cycling, it is automatically defined as follows:

However the navlist is defined, it is important to remember this: it is a static snapshot of some set of bookmarks taken at a given time. Subsequent changes to the bookmark list that was copied are not reflected in the navlist. If you add a bookmark it will not be among those cycled. But see also Cycling Dynamic Sets of Bookmarks for how to cycle dynamic sets.

You can update the navlist at any time by taking another snapshot of the same bookmark list you used for the last snapshot. For the global bookmark list just use **` C-x x : RET**’. (You can of course bind that action to a shorter key sequence if you like.)

Besides cycling among the bookmarks of the navlist (see next), once you have defined the navigation list you can use ‘C-x j N’ or ‘C-x 4 j N’ to jump to its bookmarks, as mentioned in section Different Types of Jump Commands.

Note that just because you might have used ‘C-x x B’ to define the navlist using a particular bookmark-list bookmark or the current ‘*Bookmark List*’ state, that does not mean that the ` *Bookmark List*’ state at any given time necessarily reflects the navlist bookmarks. The two are separate. You can, however, open the ‘*Bookmark List*’ so that it reflects the bookmarks currently in the navigation list, using ‘C-x x N’** (**‘bmkp-navlist-bmenu-list’).

Cycling the Navigation List

So you choose a navigation list. How do you then cycle among its bookmarks?

Commands ‘bmkp-next-bookmark’ and ‘bmkp-previous-bookmark’ cycle to the next and previous bookmark in the navigation list (with wraparound). (There are also other-window versions of these commands.)

You can bind these to any keys you like, but it’s obviously better to choose keys that are easily repeatable (e.g. by holding them pressed). Some people who are used to using MSVisualStudio might want to use ‘f2’ and ‘S-f2’ to cycle forward and backward.

Bookmark+ does not define such key bindings, but you can. What it does is define repeatable keys on the ‘bookmark-map’ keymap, which by default has prefix ‘C-x x’. To do this it binds similar commands that can be repeated by simply repeating the key-sequence suffix. These are the (default) keys:

Forward: ‘C-x x f’, ‘C-x x C-f’, ‘C-x x right’

Backward: ‘C-x x b’, ‘C-x x C-b’, ‘C-x x left’

(If you use an Emacs version prior to Emacs 22, you cannot use this prefix-key repeatable feature.)

In addition, if you use MS Windows then you can invoke the Windows ‘Open’ action on each bookmark when you cycle, to act on its file using the program associated with the file type. This lets you play music or display images in a playlist or slideshow fashion. These are the keys to do that:

Forward: ‘C-x x next’ (PageDown key)

Backward: ‘C-x x prior’ (PageUp key)

Being able to cycle among an arbitrary set of bookmarks is the most important feature of Bookmark+ cycling. The other important feature is that if the navigation list is defined by ` *Bookmark List*’ then the characteristics of that bookmark display are respected for navigation. Only the bookmarks _visible_ in ‘*Bookmark List*’ are included, and the ‘*Bookmark List*’ sort order is used for navigation.

So you can not only choose any set of bookmarks for cycling at any given time, you can also cycle among them in an order you choose. For example, if in the bookmark list display (‘C-x x e’ or ‘C-x r l’) you show only those file bookmarks that belong to a given project, and you have them sorted by file size, then cycling moves among only those files, in file-size order.

This is a main reason you will want to define bookmark-list bookmarks, which record a specific set of bookmarks and their sort order: to later choose given sets in different contexts for cycling.

Cycling Dynamic Sets of Bookmarks

The fact that the navlist is a static snapshot is a useful feature, but sometimes you might want to cycle among a particular dynamic set of bookmarks, that is, to have cycling take changes to the bookmark set into account automatically. For that, Bookmark+ provides separate cycling commands for most types of bookmark.

By default, these different kinds of cycling commands are not bound to any keys, with the exception of the commands for cycling the current file or buffer. This exception includes cycling all bookmarks for the current file/buffer (see Cycling in the Current File/Buffer and cycling only the highlighted bookmarks for the current file/buffer (see Using Highlighted Bookmarks). Keys ‘C-x x down’ and ‘C-x x C-down’ are defined for these two kinds of current-buffer cycling.

If you often want to cycle among the bookmarks of some other particular kind (e.g. only the autonamed bookmarks), then you can bind the relevant commands (e.g. ‘bmkp-next-autonamed-bookmark-repeat’, ‘bmkp-previous-autonamed-bookmark-repeat’, or their other-window versions)) to handy keys. Otherwise, you can just use the cycling commands without binding them.

Cycling in the Current File/Buffer

You can navigate the bookmarks in the current file or buffer by cycling as well as jumping. It is convenient to have dedicated keys for this, separate from the keys to cycle the navigation list. The following keys are defined, corresponding to commands ‘bmkp-next-bookmark-this-file/buffer-repeat’ and ‘bmkp-previous-bookmark-this-file/buffer-repeat’:

Next: ‘C-x x n’, ‘C-x x C-n’, ‘C-x x down’

Previous: ‘C-x x p’, ‘C-x x C-p’, ‘C-x x up’

Starting with Emacs 23.3 (Emacs fix for bug #6256), you can also use the mouse wheel to cycle: ‘C-x x’ then just rotate the wheel.

Again, you can bind any keys you want to these commands (e.g. ‘f2’, ‘S-f2’). If you do not need to use a prefix key, then bind commands ‘bmkp-next-bookmark-this-file/buffer’ and ‘bmkp-previous-bookmark-this-file/buffer’ (no -repeat).

You can also cycle among just the highlighted bookmarks in the current file or buffer – see Using Highlighted Bookmarks.

Cycling among bookmarks for the current file or buffer (whether all bookmarks or only the highlighted ones) is dynamic: the current set of bookmarks is cycled, not a static snapshot taken at some point in past. The navlist is automatically updated to the current dynamic set each time you cycle. This is different from the usual cycling of the navlist, where it is taken as a static snapshot – see The Bookmark Navigation List.

By default, you cycle among the bookmarks for the current file or buffer in order of their buffer positions, top to bottom. If you want a different order, you can customize option ‘bmkp-this-file/buffer-cycle-sort-comparer’.

Alternatively, you can use **` C-x x ,**’ to display the ` *Bookmark List*’ with only the current file/buffer’s bookmarks, sort them there, and then use ‘C-x x B’ to set the navigation list to ‘CURRENT *Bookmark List*’. In that case, you use the navlist cycling keys (e.g. ‘C-x x f’, not ‘C-x x n’), and the cycled set is a static snapshot.

Note that the keys mentioned here cycle bookmarks for the current file if visiting a file, or the current buffer otherwise. There are also commands (unbound to keys) for cycling bookmarks for the current file only or the current buffer only.

The bookmarks for the current buffer are those that were created in a buffer of exactly the same name. If one buffer visits a file ` foo.el’, and another buffer visits a different file of the same name (i.e., in a different directory), the second buffer will have the name ` foo.el<2>’. The buffer name is recorded when you create a bookmark. If you later use same-buffer cycling then the bookmarks cycled are only those created with the same buffer name as the current buffer.

This is the reason why the ‘*-file/buffer*’ commands are bound to keys. They are usually what you want. They try first to work with bookmarks for the same file as the current buffer, if it is visiting a file.

Autonamed Bookmarks - Easy Come Easy Go

Sometimes it is convenient to quickly create and delete bookmarks whose names you don’t really care about. That is the purpose of autonamed bookmarks. An autonamed bookmark has a simple name provided automatically, and it does not record any region information – it records only a position. An autonamed bookmark is nevertheless an ordinary, persistent bookmark.

‘C-x x RET’ creates a bookmark at point without prompting you for the name. It is named using the current buffer name preceded by the position in the buffer. For example, the default name of the autonamed bookmark in buffer ` foo.el’ at position 58356 is ` 000058356 foo.el’.

When you jump to any bookmark, the actual destination can differ from the recorded position, because the buffer text might have changed. In that case, the position you jump to has been automatically relocated using the recorded bookmark context (some buffer text surrounding the original position).

If option ‘bmkp-save-new-location-flag’ is non-‘nil’ then, after jumping, the recorded position of the bookmark is automatically updated to reflect the new location jumped to. This is true for any bookmark.

In the case of an autonamed bookmark, the bookmark name typically reflects the recorded position when you create it. And when you jump to it, both the name and the recorded position are updated to reflect the jump destination. So jumping to an autonamed bookmark keeps its persistent record in sync with the buffer location.

You will thus notice that the names of autonamed bookmarks can change as you visit them (e.g. cycling). The bookmarks are automatically repositioned following their recorded contexts, and their names reflect that repositioning.

It is only when you jump to a bookmark that it is repositioned this way, and only if needed. It is normal that some bookmarks become somewhat out of sync with their original positions as you edit the text in the buffer. In addition, if you highlight bookmarks then you will notice the highlighting move as you edit nearby text. The recorded bookmark has not changed, but its highlight has moved. The highlight moves more or less as if it were an Emacs marker. When you jump to the bookmark and it is thus updated, the highlight moves back to the recorded position, adjusted perhaps to fit the recorded context.

‘C-x x RET’ is ‘bmkp-toggle-autonamed-bookmark-set/delete’, and it does double duty. If an autonamed bookmark is under the cursor, then ‘C-x x RET’ deletes it. Easy creation, easy deletion. Because of this toggle behavior, there is at most one autonamed bookmark at any given buffer position.

‘C-x x RET’ has a third use: With a prefix argument, it prompts you to confirm the deletion of ALL autonamed bookmarks for the current buffer.

(You can also use ‘C-x x delete’ (that’s the ‘delete’ key), bound to ‘bmkp-delete-bookmarks’, to delete individual bookmarks under the cursor or all bookmarks in the buffer. This is not limited to autonamed bookmarks.)

In addition to ‘C-x x RET’, you can create autonamed bookmarks using these commands:

Autonamed bookmarks are normal bookmarks. In particular, they are persisted. If you do not care to persist them, you can ensure that they are automatically deleted by adding ‘bmkp-delete-autonamed-this-buffer-no-confirm’ to ‘kill-buffer-hook’ and ‘bmkp-delete-autonamed-no-confirm’ to ‘kill-emacs-hook’:

(add-hook 'kill-buffer-hook 'bmkp-delete-autonamed-this-buffer-no-confirm) (add-hook 'kill-emacs-hook 'bmkp-delete-autonamed-no-confirm)

You can customize the format of autonamed bookmarks using options ‘bmkp-autoname-bookmark-function’ and ‘bmkp-autoname-format’.

For example, if you want autonamed bookmarks to show the line and column numbers, in the form L<num>,C<num> <buffer>, where <num> is a sequence of decimal digits and <buffer> is the buffer name, then you can use a function such as this as the value of ‘bmkp-autoname-bookmark-function’:

(defun my-auto-l+c-name (position) "Return a name for POSITION that uses line & column numbers." (let ((line (line-number-at-pos position)) (col (save-excursion (goto-char position) (current-column)))) (format "L%d,C%d %s" col line (buffer-name))))

To enable Bookmark+ to recognize such bookmarks as autonamed, you would then set ‘bmkp-autoname-format’ to the format specification "^L[0-9]+,C[0-9]+ %B", to match their names. Here, the **` %B**’ is a Bookmark+ format specifier that corresponds to the buffer name.

Recognizing the buffer name in an autonamed bookmark is important or commands that act only on autonamed bookmarks for a specific buffer. That includes commands ‘bmkp-autonamed-this-buffer-jump’ and ‘bmkp-delete-all-autonamed-for-this-buffer’.

You use the special format specifier ` %B’ for the buffer name, instead of just `%s’, because the format can have multiple ` %’ sequences, and the buffer name could be anywhere in the bookmark name. Depending on the buffer, the buffer name could thus be confused with other text in the bookmark name, unless you use ` %B’ to show where it is. You can use just **` %s**’ for it if there is no risk of ambiguity. (Use ` %s’ in ‘bmkp-autoname-bookmark-function’ to insert the buffer name.)

Temporary Bookmarks

Autonamed bookmarks are easy-come-easy-go in the sense that ‘C-x x RET’ either sets (creates) one or deletes the one under the cursor. But what about temporary bookmarks in general? What if you want only bookmarks that are temporary, that is, not saved to disk? Or what if you want certain kinds of bookmarks to always be temporary? Or what if you want to toggle whether particular bookmarks get saved automatically?

Temporary Bookmarking Mode

As always, you can control whether the bookmarks in the current bookmark list are saved automatically using option ‘bookmark-save-flag’. Remember that you can toggle this option using command ‘bmkp-toggle-saving-bookmark-file’ (bound to **` M-~**’ in the bookmark-list buffer). Remember too that you can at any changing the set of bookmarks that are susceptible to being saved.

You could, for example:

1. Use ‘C-x x 0’ (‘bmkp-empty-file’) to create a new, empty bookmark file.

2. Use ‘C-x x L’ (‘bmkp-switch-bookmark-file-create’) to switch to using that new, empty bookmark file.

3. Use ‘M-x bmkp-toggle-saving-bookmark-file’ to turn off auto-saving bookmarks to disk.

This is essentially what the minor-mode toggle command ‘bmkp-temporary-bookmarking-mode’ does. When in this minor mode, bookmarks that you create are stored on the new bookmark list, which is not automatically saved to disk. If you do not explicitly save it yourself then the bookmarks are lost when your Emacs session ends – they are only temporary.

This command is bound to ‘M-L’ in the bookmark-list display buffer (‘*Bookmark List*’). The suffix ‘L’ indicates that this has to do with **l**oading a bookmark file. See Using Multiple Bookmark Files.

In the bookmark-list display, temporary bookmarking mode is indicated in the mode line by ‘TEMPORARY Bookmarking’ in place of ‘Bookmarks’ as the mode name.

Making Bookmarks Temporary

Instead of simply switching to a temporary bookmark list, so that all bookmarking is only temporary, you more often want to have some bookmarks be temporary while still ensuring that others get saved. Or you temporarily want all new bookmarks that you create and all bookmarks that you update to be temporary, without affecting other, unchanged bookmarks.

You can control this at the level of individual bookmarks, types of bookmarks, or all bookmarks whenever they are set (created or updated).

You can delete all such temporary bookmarks from the current bookmark list using command ‘bmkp-delete-all-temporary-bookmarks’ (or by using ‘X M’ to mark them in the bookmark-list display and then hitting ‘D’ to delete thems).

In the bookmark-list display (buffer ‘*Bookmark List*’), temporary bookmarks are indicated with the mark ‘X’ in the same column where the annotation mark ‘a’ would otherwise appear.

Automatic Bookmarking

You might find automatic bookmarking useful. The idea is that Emacs sets a bookmark for you automatically.

Bookmark+ can do this either when you perform some action (besides explicitly bookmarking) or whenever you are idle for a given period of time (option ‘bmkp-automatic-bookmark-mode-delay’).

Automatic Bookmarking Using a Hook

To automatically set a bookmark whenever some hook is run, put function ‘bmkp-set-automatic-bookmark’ on the hook. For example, to set a bookmark at a definition jumped to whenever you use Imenu, you can do this:

(add-hook 'imenu-after-jump-hook #'bmkp-set-automatic-bookmark)

The bookmark is an autonamed bookmark.

Automatic Idle-Period Bookmarking

Automatic idle-period bookmarking creates bookmarks at spots where you spend some time (idly). It uses ‘bmkp-set-automatic-bookmark’, so the bookmarks created are autonamed.

How many such bookmarks would you want? And how close together? Bookmark+ tries to provide some user options that let you get the behavior you want. Except for ‘bmkp-automatic-bookmark-mode-delay’ they apply to ‘bmkp-set-automatic-bookmark’, so they affect both idle-period bookmarking and automatic bookmarking on a hook.

In general, you probably don’t want such bookmarks to be created too often or too close together. You probably don’t care about the names of the bookmarks created, and you don’t want to be interrupted to have to name them. You probably want automatic idle-period bookmarking to be per-buffer, but you might sometimes want to turn it on or off for all buffers. You might want more than one automatic bookmark on a given line, but probably not. Finally, you might or might not want such bookmarks to be temporary (current session only) or highlighted.

Mode ‘bmkp-automatic-bookmark-mode’ is a local minor mode, which means that it is buffer-specific. The command of the same name turns the mode on and off. When the mode is on, the minor-mode indicator (“lighter”) ‘Auto-Bmk’ is shown in the mode line for the buffer. You can customize this indicator (removing it, if you like), using option ‘bmkp-automatic-bookmark-mode-lighter’.

Command ‘bmkp-global-automatic-bookmark-mode’ turns on the mode in all buffers, that is, it is global, not local. Regardless of whether you use the mode locally or globally, a bookmark is created automatically only in the current buffer. That is, a buffer must be current (selected) for an automatic bookmark to be created there – it’s not enough that the mode be enabled in the buffer.

Option ‘bmkp-automatic-bookmark-set-function’ defines the bookmark-setting function. By default, its value is ‘bmkp-set-autonamed-bookmark-at-line’, which sets an autonamed bookmark at (the beginning of) the current line. If you want bookmarks to be created automatically then you typically want them to be autonamed, both because the name is unimportant and because setting an autonamed bookmark requires no interaction on your part. But you can use any setting function you like as the option value. (You can always rename an autonamed bookmark later, if you want to keep it and give it a meaningful name.)

Option ‘bmkp-automatic-bookmark-min-distance’ is the minimum number of characters between automatic bookmark positions. If the cursor is currently closer to some existing automatically created bookmark, then no automatic bookmark is set at point. If you set this to ‘nil’ then there is no limit on how close the bookmarks can be. (But there is only one autonamed bookmark at any given position.)

If you want automatically created bookmarks to be temporary (not saved to your bookmark file), then customize option ‘bmkp-autotemp-bookmark-predicates’ so that it includes the kind of bookmarks that are set by ‘bmkp-automatic-bookmark-set-function’. For example, if automatic bookmarking sets autonamed bookmarks, then ‘bmkp-autotemp-bookmark-predicates’ should include ‘bmkp-autonamed-bookmark-p’ or ‘bmkp-autonamed-this-buffer-bookmark-p’ (it includes both of these by default). Remember that you can toggle whether a given bookmark is temporary or savable, using ‘M-X’ in the bookmark-list display (buffer ‘*Bookmark List*’).

If you want the bookmarks to be automatically highlighted, then customize option ‘bmkp-auto-light-when-set’ to highlight bookmarks of the appropriate kind. For example, to highlight autonamed bookmarks set it to ‘autonamed-bookmark’.

NOTE: If you use Emacs 20, then by default ‘bmkp-automatic-bookmark-mode’ is global rather than local. The doc string tells you how to make it local instead. If you use Emacs 21, then ‘bmkp-automatic-bookmark-mode’ is local but there is no global mode, ‘bmkp-global-automatic-bookmark-mode’. This is because Emacs 21 does not support ‘define-globalized-minor-mode’.

Automatic Info Bookmarking

If you enable global minor mode ‘bmkp-info-auto-bookmark-mode’, each Info node you visit is bookmarked automatically, using the default bookmark name, which is the Info manual name plus the node name. For example, node Lisp Data Types in the Elisp manual gives you a bookmark named ` (elisp) Lisp Data Types’.

With the mode enabled, when you visit an Info node an existing bookmark with the same name is always updated. If no such bookmark exists then a new one is created if option ‘bmkp-info-auto-type’ has value ‘create-or-replace’. If it has value ‘update-only’ then no new bookmark is created. The default option value is ‘update-only’. You can toggle the value using command ‘bmkp-toggle-info-auto-type’.

With ‘bmkp-info-auto-bookmark-mode’ enabled, even if you have created Info bookmarks with the default names manually, they are updated automatically. In particular, updating a bookmark increments the recorded number of visits to the Info node and the time of the last visit.

You can sort bookmarks in the bookmark-list display by the time of last visit, using ‘s d’, or by the number of visits, using ‘s v’.

This gives you an easy way to see which parts of the manuals you have visited most recently and how much you have visited them. Showing only Info bookmarks gives you the effect of a persistent mini-manual of just the visited Info nodes. Turn the mode off anytime you do not want to record Info visits.

Also useful in this context, though not related to bookmarking, is the ability to save your Info history persistently, so links to visited nodes are shown using a different face. This makes it easy to see which parts of a manual you have already looked at. (And checking a bookmark to a visited node shows you how much you have visited it.)

If you use library Info+ (info+.el) then you have this complementary ability save your Info history list persistently. Just enable minor mode `Info-persist-history-mode’.

Highlighting Bookmark Locations

You can highlight the location (destination) of a bookmark. For this feature you need library bookmark+-lit.el in addition to the other Bookmark+ libraries.

You might never want to highlight a bookmark, or you might want to highlight most or even all bookmarks, or your use of highlighting might fall somewhere between. It depends on what kind of bookmarks you have and how you use them. Bookmark+ lets you choose. By default, no bookmarks are highlighted.

Defining How to Highlight

By default, autonamed bookmarks are highlighted differently from non-autonamed bookmarks. Bookmark highlighting uses a style and a face. The available styles are these:

You can customize the default styles and faces to use for autonamed and non-autonamed bookmarks. You can also customize the fringe bitmaps to use.

Note: A region, position, or line highlight acts more or less like an Emacs marker: it moves with the surrounding text. As you edit the text in the buffer, the highlighted location can thus become out of sync with the recorded position. This is normal. When you jump to the bookmark, its highlight is automatically repositioned to the recorded location, possibly adjusted according to the the surrounding context.

In addition to the default highlighting, which you can customize, you can set the highlighting for individual bookmarks and particular sets of bookmarks (overriding their default highlighting). These individual settings are saved as part of the bookmarks themselves.

In the bookmark list (buffer ‘*Bookmark List*’):

Globally, you can use ‘M-x bmkp-set-lighting-for-bookmark’ to set the highlighting for a given bookmark.

Each of these commands prompts you (with completion) for the style and face to set, as well as for a condition that controls whether to highlight. Each of these is optional – just hit ‘RET’ (empty input) at its prompt to skip setting it.

The condition is an EmacsLisp sexp that is evaluated whenever an attempt is made to highlight the bookmark. Any resulting value except ` :no-light’ highlights the bookmark. The sexp can refer to the variables ‘this-bookmark’ and ‘this-bookmark-name’, whose values are the bookmark to be highlighted and its name, respectively.

So, for example, if you wanted to be prompted each time before highlighting a certain bookmark you might set its highlighting condition to a sexp such as this:

(or (y-or-n-p (format "Highlight `%s' " this-bookmark-name)) :no-light)

If you hit ‘n’ at the prompt then ` :no-light’ is returned and the bookmark is not highlighted.

In the bookmark-list display, a pink-background, one-character highlight is used next to each bookmark that has a highlight override wrt the default. You can see what that override setting is by using ‘C-u C-h RET’ – look for the ‘lighting’ entry in the bookmark definition.

Highlighting On Demand

You can highlight or unhighlight a bookmark or a set of bookmarks on demand.

In the bookmark list (buffer ‘*Bookmark List*’):

Globally:

The default bookmark for ‘C-x x u’ is the same bookmark that is unhighlighted by ‘C-x x C-u’: a (highlighted) bookmark at point (preferably) or on the same line. The latter key binding just saves you having to hit ‘RET’ to pick the default.

When you use ‘C-x x h’, you can use a prefix argument to override both the default highlighting and any highlighting that is recorded for the bookmark itself. You are prompted for the style or face to use:

Highlighting Automatically

You can also highlight automatically, whenever you set (create) a bookmark or jump to one. This is controlled by these options:

You can choose any of these values for either option:

The first three values highlight only the bookmark being set or jumped to.

Be aware that, depending on the setting, highlighting can take a while.

Using Highlighted Bookmarks

Once you have highlighted bookmarks, what can you do with them? Obviously, the highlighting can help you distinguish and find bookmarks visually. But highlighting also serves as yet another way to define sets: the highlighted vs unhighlighted bookmarks.

Any command that operates on a set of bookmarks can be applied to one or the other of these two sets. Bookmark+ defines only a few such operations, but you can easily define others.

In addition to such specific commands, you can also apply general operations to the highlighted or unhighlighted bookmarks, using the bookmark-list display (‘*Bookmark List*’). ‘H S’ shows only the bookmarks that are currently highlighted, and ‘H M’ marks them. You can then perform any of the available bookmark-list operations on them.

Globally, you can use these keys:

You can use command ‘bmkp-insert-bookmark-link’ to create links in any Emacs text that jump to particular bookmarks when you follow them (by hitting ‘RET’ or clicking ‘mouse-2’). If you hit ` ?’ or double-click ‘mouse-1’ on such a bookmark link then the bookmark is described, showing the same information as **‘C-h M’** (‘bmkp-describe-bookmark’).

You are prompted for the bookmark to link. If the region is active and nonempty then the link is put on its text. Otherwise, you are prompted for the link text, which is inserted. The default link text is the bookmark name in this case.

The bookmark linked can be of any type.

This simple feature lets you easily create “launching pads” for different sets of bookmarks: buffers or files that consist of bookmark links and any other text you like. This gives you yet another way to organize bookmarks (and so also the files, directories, etc. that they target).

If you also use library font-lock+.el then the links appear with face ‘link’, even in a font-locked buffer. (Library font-lock+.el just provides this feature of allowing non-font-lock highlighting in a font-locked buffer. See http://lists.gnu.org/archive/html/emacs-devel/2014-08/msg00540.html.)

The links you create this way are not persistent, but you can of course re-create them using Lisp.

You can also easily define OrgMode links that jump to bookmarks. These links are persistent. Again, the bookmark linked can be of any type.

You can use the standard Org command ‘org-store-link’ (‘C-c l’) in buffer ‘*Bookmark List*’ to store a link to the bookmark at point. (This is also item Store Org Link in the mouse-3 popup menu.)

Outside buffer ‘*Bookmark List*’ you can use command ‘bmkp-store-org-link’ to store a link to any bookmark. You are prompted for the bookmark name. You can even enter the name of a bookmark that does not yet exist. (This is also item Store Org Link To… on menu Bookmarks.)

If you use a numeric prefix arg with either command then the bookmark link stored will be for jumping to the bookmark in the same window. Without a numeric prefix arg, the link will use another window. (Org mode defines other behaviors for non-numeric prefix args, such as ‘C-u C-u’.)

As usual, to insert a bookmark link, you use command ‘org-insert-link’. Enter the name of the target bookmark at the prompt. In Org mode you can use the usual Org key bindings to follow the link. In any mode you can use standard Org command ‘org-open-at-point-global’ (not bound to a key by default).

Bookmark Menus

Two menu-bar menus for Bookmark+ have already been mentioned:

Access to bookmarks for the currently visited file or current buffer is available as a Bookmarks Here submenu of the major-mode menu-bar menu in modes Info and Buffer-Menu, if option ‘bmkp-add-bookmarks-here-menu-flag’ is non-‘nil’.

The menu items let you cycle among bookmarks in the current file/buffer or access the bookmark-list display for only those bookmarks.

If you use library Dired+ then the same access is available in Dired mode on menu-bar menu Dir > Bookmark > Here.

If you use library Imenu+ then the same access is available in an Imenu submenu Bookmarks Here. In this case there are also menu items to jump to each bookmark in the file/buffer. For Imenu, display of the menu is controlled by option ‘imenup-show-bookmarks-flag’.

Use Bookmark+ with Icicles

Icicles enhances your use of Bookmark+ in several ways.

When jumping to a bookmark, you can narrow the completion candidates to bookmarks of a particular type (e.g. Info, using ‘C-M-i’; remote, using ` C-M-@’; region, using ‘C-M-r’). You can narrow again (and again), to another bookmark type, to get the intersection (e.g. remote Info bookmarks that define a region).

You can also narrow against different bookmark-name patterns (e.g. regexps) – so-called progressive completion. And take the complement (e.g., bookmarks whose names do not match ` foo.*2010.*bar’). (This is not special to bookmarks; it is standard Icicles practice.)

In Icicle mode, several of the Bookmark+ keys are remapped to corresponding Icicles multi-commands. A bookmark jump key thus becomes a bookmarks browser. For example, ‘C-x j d’ browses among any number of Dired bookmarks.

A single key can set a bookmark or visit bookmarks. This key is whatever command ‘bmkp-bookmark-set-confirm-overwrite’ would normally be bound to – e.g. ‘C-x r m’. A prefix argument controls what it does. If negative (‘M--’), jump to (browse) bookmarks. Otherwise, set a bookmark using ‘bmkp-bookmark-set-confirm-overwrite’, as follows:

During completion of a bookmark name, most features of the bookmark-list display (see The Bookmark List Display) are available on the fly. Buffer ‘*Completions*’ acts like a dynamic version of ‘*Bookmark List*’:

You can match any or all of the parts. For example, you can match bookmarks that have tags by typing this regexp: ` C-M-j . * C-M-j S-TAB’.

Each ‘C-M-j’ inserts ` ^G\n’, which is `icicle-list-join-string’, the string used to join the parts. This regexp says, “match the completion candidates that have all three parts (two join strings), hence some tags.

You can turn off the use of multi-completion candidates for subsequent commands, so only bookmark names are used, by hitting ‘M-m’ in the minibuffer. You can think of this as similar to using ‘M-t’ in ‘*Bookmark List*’ to toggle showing file names. You can make not showing files and tags the default behavior by customizing `icicle-show-multi-completion-flag’.

During file-name completion, you can do any of the following on the fly:

There are 25 Icicles commands for searching bookmark destinations! The most general is ‘icicle-search-bookmark’. Others let you search specific kinds of bookmarks, or bookmarks having various combinations of tags.

During Icicles search (of anything, not just a bookmark destination), you can save sets of completion candidates, which means sets of search hits, as bookmarks. And Icicles lets you use set operations (complement, union, intersection, difference etc.) on the current set of search hits.

When you “jump” to an Icicles search-hits bookmark, its recorded search hits are restored to Icicles search as completion candidates, either replacing the current candidates or adding to them.

You can thus save and later return to different sets of search results using different bookmarks. You can “jump” to an Icicles search-hits bookmark during any Icicles search, whether you search a file, a buffer, multiple files, or multiple buffers.

See Also: Icicles - Bookmark Enhancements.

Bookmark Compatibility with Vanilla Emacs

Bookmark+ is generally compatible with GnuEmacs versions 20 and later. You can use bookmarks with Bookmark+ regardless of whether they were created using Bookmark+ or vanilla Emacs (i.e., library bookmark.el).

But for best results, if you have bookmarks that you created using Bookmark+ then use Bookmark+, not vanilla Emacs, to access them. This section provides details.

Set user option ‘bmkp-propertize-bookmark-names-flag’, depending on your usage scenario (the default is ‘t’ for Emacs 21 and later, ‘nil’ for Emacs 20):

  1. Set it to ‘nil’ if you will often be going back and forth between using Bookmark+ and using vanilla Emacs. (Do this also if you use Emacs 20.)
  2. Set it to non-‘nil’ if you instead always use only Bookmark+ (with Emacs 21 or later), or you use vanilla Emacs only to jump to bookmarks but never to update or create bookmarks.

#1 is VERY IMPORTANT. You can lose data if you do not respect it.

The reason for rule #1 is this: When the option is non-‘nil’ Bookmark+ writes bookmarks to your bookmark file in a format that can be read and used by vanilla Emacs (21 and later) but which vanilla Emacs then saves as unreadable. If the option value is ‘nil’ there is no such problem.

#2 is not a requirement. It is just a good idea, to be able to take better advantage of Bookmark+. If you set the option to ‘nil’ then you cannot use multiple bookmarks that have the same name. Vanilla Emacs does not make good use of such critters, but Bookmark+ does. Having multiple bookmarks with the same name is particularly useful for autofiles. It means you can have different autofiles in different directories but with the same name. See Autofile Bookmarks.

Here is what happens when ‘bmkp-propertize-bookmark-names-flag’ is non-nil:

Besides its name, which is what you see and use most of the time, a bookmark contains other information such as the target location, textual context hints, and last access time. Non-‘nil’ ‘bmkp-propertize-bookmark-names-flag’ has no effect on vanilla Emacs, but it causes Bookmark+ to put the full bookmark information on the bookmark name as a text property.

The name thus encapsulates all of the information contained in the full bookmark of which it is part. Knowing the name is then enough to know everything about the bookmark. Part of the bookmark (its name) refers to the whole of it. In Lisp this self-reference is implemented using circular structures.

When Bookmark+ saves such circular structures to your bookmark file, if the option is non-‘nil’ then it takes care to do so in such a way that they can be read in again when your bookmark file is loaded. In Lisp terms, it binds ‘print-circle’ to non-‘nil’ when it writes your bookmarks. If the option value is ‘nil’ then the circularity (self-reference) is removed before your bookmarks are saved. Either way, the file is readable.

Vanilla Emacs (21 and later) has no problem reading your bookmark file if it contains such circular structures. But if you then use it to save the file again, the Lisp code it writes has invalid Lisp ‘read’ syntax (because it does not remove the circularity but it also does not bind ‘print-circle’ to non-‘nil’).

If that happens, the result is a bookmark file that is unreadable. It cannot be loaded into either vanilla Emacs or Bookmark+. If you do not have an uncorrupted backup version of the file to revert to, then you will need to edit it by hand to clean it up.

So do not let that happen to you! For best results use only Bookmark+ to access bookmarks created using Bookmark+.

If you must use vanilla Emacs with your bookmarks, then make sure they are not saved by Bookmark+ with the option non-‘nil’: Using Bookmark+, set the option to ‘nil’ and then save the file.

That is:

  1. ‘M-x set-variable bmkp-propertize-bookmark-names-flag nil’, to stop using propertized bookmark names.
  2. ‘C-x x e’ or ‘C-x r l’, to display the bookmark list.
  3. ‘g’, to refresh the display.
  4. ‘S’, to save the bookmark list.
  5. ‘M-x bmkp-save-menu-list-state’, to save the display state.

Then you can use your bookmark file with vanilla Emacs (but without the possibility of having multiple bookmarks with the same name).

Note that when the option value is non-‘nil’, propertized bookmark names are saved not only to your bookmark file but also to any full snapshots you create of the bookmark-list display state using command ‘bmkp-bmenu-define-full-snapshot-command’ (‘C-c C-C’, aka ‘C-c C-S-c’). See State-Restoring Commands and Bookmarks.

Here are screenshots of the various Bookmark+ menus. Using the menus is a good way to learn some of the features (and their key bindings).

Bookmark+ adds two items to the menu bar Edit menu:

BookmarkPlusMenuBarEditMenu

`mouse-3' Popup Menu in `*Bookmark List*'

It has actions for the individual bookmark you point to when you pop it up.

BookmarkPlusThisBookmarkMenu

Bookmark+ Menu-Bar Menu in `*Bookmark List*'

The same menu is available on ‘C-mouse-3’.

Bookmark+

BookmarkPlusMenuBarMenu

It has submenus Icicles (if you use Icicles), Jump To, Delete, Mark, Omit, Show, Sort, Search, Tags, Highlight, Toggle, Bookmark File, and Define Command.

The Jump To menu has submenus Icicles (if you use Icicles) and With Tags. The Icicles submenu has its own submenu With Tags.

The Mark menu has submenu Bookmarks of Type.

The Show Menu has submenu Only Bookmarks of Type.

Icicles submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuIcicles

Jump To submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuJump

Icicles submenu of Jump To submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuJumpToIcicles

With Tags submenu of Icicles submenu of Jump To submenu of Bookmark+ menu-bar menu (Emacs 21+ only)

BookmarkPlusMenuBarMenuIciclesWithTags

With Tags submenu of Jump To submenu of Bookmark+ menu-bar menu (Emacs 21+ only)

BookmarkPlusMenuBarMenuWithTags

Toggle submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuToggle

Delete submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuDelete

Mark submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuMark

Bookmarks of Type submenu of Mark submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuMarkOfType

Omit submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuOmit

Show submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuShow

Only Bookmarks of Type submenu of Show submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuShowOfType

Edit submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuEdit

Sort submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuSort

Search submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuSearch

Tags submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuTags

Highlight submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuHighlight

Bookmark File submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuBookmarkFile

Define Command submenu of Bookmark+ menu-bar menu

BookmarkPlusMenuBarMenuDefineCommand

Vanilla Bookmarks Menu

The vanilla Bookmarks menu provided by Emacs is typically a submenu of the Edit menu bar menu. Bookmark+ modifies it by adding several Bookmark+ items and submenus.

Bookmarks

BookmarkPlusBookmarkMenuBarMenu

Jump To submenu of Bookmarks menu-bar menu

Same as Bookmark+ submenu Jump To

Tags submenu of Bookmarks menu-bar menu

BookmarkPlusBookmarksTagsMenu

Toggle submenu of Bookmarks menu-bar menu

Same as Bookmark+ submenu Toggle

New/Update submenu of Bookmarks menu-bar menu

BookmarkPlusBookmarksNewUpdateMenu

Delete submenu of Bookmarks menu-bar menu

BookmarkPlusBookmarksDeleteMenu

Here (This File/Buffer) submenu of Bookmarks menu-bar menu

BookmarkPlusBookmarksHereMenu

Highlight submenu of Bookmarks menu-bar menu

BookmarkPlusBookmarksHighlightMenu

Annotate submenu of Bookmarks menu-bar menu

BookmarkPlusBookmarksAnnotateMenu

Vanilla File Menu

Bookmark+ adds submenu ‘Find File or Autofile’ to the vanilla File menu provided by Emacs.

BookmarkPlusFindFileOrAutofileMenu

`*Bookmark List*' Help Screenshots

Here are screenshots for the ‘*Bookmark List*’ help display (available via `?’ or ‘C-h m’). Yes, the help is so long that several screenshots are required to capture it all.

BookmarkPlusHelp1 BookmarkPlusHelp2 BookmarkPlusHelp3 BookmarkPlusHelp4 BookmarkPlusHelp5 BookmarkPlusHelp6 BookmarkPlusHelp7 BookmarkPlusHelp8 BookmarkPlusHelp9 BookmarkPlusHelp10

Here is an icon you can use to indicate image-file bookmarks in the ‘*Bookmark List*’ display, if you don’t have another that you prefer. Save it and set option ‘bmkp-image-bookmark-image-file’ to its location.

BookmarkPlusImageFileDefaultIcon

CategoryBookmarking CategoryHypermedia CategoryPersistence CategoryProgramming CategoryRegion CategoryWThirtyTwo CategoryProgrammerUtils SessionManagement CategoryDirectories CategoryProject