The internal bookmark format (data structure) used by Bookmark+ is compatible with that of vanilla GnuEmacs. It extends that structure in new ways, to accommodate new bookmark types.
With Bookmark+ you can use bookmarks that were created with any Emacs version in any other Emacs version. But see also Compatibility, below.
Some basic keys you can use anywhere:
‘C-x p m’
‘C-x j j’
C-x p t + a’
‘C-x r l’
Some keys you can use in your bookmarks list (from
‘C-x r l’):
T m +’. Hit
‘RET’to enter each tag you type, then hit
‘RET’with empty input when done.
‘M-DEL’(just like in Dired)
M-d >’. Enter a name for the Dired buffer.
Some keys you can use in DiredMode:
‘C-x r m’
‘M-b’(you need Dired+ for this)
Bookmark+ is composed of these libraries:
The main Bookmark+ library is
bookmark+.el. The other required libraries are
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
Put the directory of these libraries in your
‘load-path’ and add this to your init file:
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
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
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.
Besides the EmacsWiki ElispArea, which always has the latest source files for Bookmark+ you can the get Bookmark+ files in the following ways:
‘package-archives’. Then use
‘M-x list-packages’and click `bookmark+’ in the list of available pacakges. Use code like this to add
‘melpa’to the list of available archives:
(when (> emacs-major-version 23) (require 'package) (package-initialize) (add-to-list 'package-archives '("melpa" . "http://melpa.milkbox.net/packages/") 'APPEND))
Here is an overview of some of the features that Bookmark+ provides. Some of these are detailed further below.
‘bmkp-use-region’). (Region activation is not supported for Gnus bookmarks.)
‘ls’switches, which files are marked, which subdirectories are inserted, and which (sub)directories are hidden.
‘*Bookmark List*’– a list of bookmarks. Jumping to such a bookmark restores the recorded sort order, filter, markings, title, and omit list.
desktop.el– use command
‘C-x p K’). You can “jump” to (that is, restore) a saved desktop. A desktop includes:
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.
‘occur’buffer, without first visiting them.
‘*Bookmark List*’display, a
‘mouse-3’popup menu has actions for the individual bookmark that you point to when you click the mouse.
‘*Bookmark List*’display, a complete menu bar menu, Bookmark+, is available. The same menu is available on
‘C-mouse-3’. It has submenus Jump To, Mark, Omit, Show, Sort, Tags, Highlight (needs library bookmark+-lit.el, and Define Command.
This is buffer
‘*Bookmark List*’, aka the bookmark “menu list” (a misnomer), which you display using
‘C-x p e’ (or
‘C-x r l’). See Bookmark List Display.
‘M-a’) or query-replace (
‘M-q’) the targets (destination files or buffers) of the marked bookmarks, in the current bookmark-list sort order. For Emacs 23 and later, you can even search incrementally (
‘M-s a C-s’, or
‘M-s a C-M-s’for regexp).
M-d >’ to open Dired for just the local file bookmarks that are marked (`
‘C-x r m’(
‘bmkp-bookmark-set-confirm-overwrite’), choosing from existing bookmarks for the same buffer. This makes it easy to update a nearby bookmark (e.g. relocate it). With a numeric prefix argument (or if there are no bookmarks for the buffer), you can choose from all bookmarks.
>’), flagged for deletion (
‘D’), tagged (
‘t’), temporary (
‘X’), annotated (
‘a’), and modified (unsaved) (
‘*’). It also shows the current sort order.
>’) and there are other lines with the same indicator that are listed after the current line, then the indicator shows
‘N/M’, where N is the number indicated through the current line and M is the total number indicated. Otherwise, it shows just
Although vanilla Emacs lets you load different bookmark files, it does not support this feature well, and the behavior can even becontradictory. 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.
When you want to jump to a bookmark of a specific type (e.g. Dired), you can use a command that offers only such bookmarks as completion candidates.
‘C-x p’is used for bookmark keys, in general. The vanilla keys on prefix
‘C-x r’are still available also, but that prefix is shared with register commands, making it less convenient for bookmarks. Using
‘C-x p’lets you focus on bookmarks.
‘C-x p c’is for setting various kinds of bookmarks.
‘C-x 4 j’(for other-window) are used for bookmark jump commands. Again, a dedicated prefix key helps you focus on one kind of action (jumping).
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. (Note that the keymap for setting bookmarks is bound to a prefix in
‘C-x p c’
‘C-x 4 j’
In addition, mode-specific bookmarking commands are bound in some other modes: Occur, Compilation (including Grep), Buffer-menu, 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.
C-x p ?’ (command
‘bmkp-describe-bookmark’describes any bookmark. With a prefix argument, it shows you the full information that defines it (internal form).
‘C-h C-RET’) describes the bookmark under the cursor. The description is as complete as possible – for example, for an image-file bookmark the complete EXIF image metadata is shown. (This is only for Emacs 22 and later, and only if you have command-line tool
‘exiftool’installed. See standard Emacs library
image-dired.elfor more information about
‘exiftool’.) And again, a prefix arg (
‘C-u C-h RET’) means show the full (internal) bookmark information.
‘M-x bmkp-bmenu-mode-status-help’shows detailed information about the current state of the bookmark list. Click button
‘Doc in Commentary’or button
‘Doc on the Web’to access the complete documentation. (Use button
‘Customize’to customize all Bookmark+ faces and options.)
‘C-h m’are the same as
‘M-x bmkp-bmenu-mode-status-help’. (
‘C-h m’in the bookmark list does not show you info about minor modes. If you want that, use
‘bookmark-plus’group customization buffer (
‘M-x customize-group bookmark-plus’), click button
‘*’. Likewise, bookmarks that have tags (marked with
‘t’); bookmarks that have annotations (
‘a’); and bookmarks that are temporary (
‘X’), meaning that they will not be saved.
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.
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
See the doc strings of command
‘bookmark-set’ (Bookmark+ version) and options
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+ 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:
‘*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
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 p 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.
Before getting into the topic of automatic saving, let me say this clearly once: Back up your bookmark file(s)!
I recommend that you set option
‘t’, so that you get numbered backups. See also nodes
‘Backup Names’ and
‘Backup Deletion’ in the Emacs manual. (Bookmark+ creates backups when your bookmark file is saved. Until bug #12507 is fixed, vanilla Emacs does not.)
‘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 unmodify 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
‘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.
When you jump to a bookmark, you can use completion to specify the bookmark name.
‘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: `
-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 j’. For instance,
‘bmkp-dired-jump-other-window’ is bound to
‘C-x j 4 d’.
More precisely, the bookmark jump commands are on the prefix maps
‘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.
If you do not remember the different type-specfic bindings, you can use commands
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 non-directory 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
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
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.
‘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’ 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
‘bmkp-bmenu-define-jump-marked-command’) in the bookmark list.
‘*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 p 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’ (
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.
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
‘diredp-do-bookmark’) in Dired to create an autofile bookmark for each of the marked files in the Dired buffer. Even if you never use those bookmarks for navigating to the files, you can use them with tags to organize the files and thus operate on subsets of them.
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) a bookmark. There are also some commands, such as
C-x p t + a’) and
‘C-x p 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 p 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 p t’ — use
‘C-x p 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.
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!
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 p 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.
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.
‘C-x p 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
‘C-x p 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.
‘C-x p 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’ 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-bmenu-make-sequence-from-marked’ creates a sequence from the marked bookmarks in the bookmark-list display, in their current order.
‘bmkp-create-dired-bookmarks-recursive’ creates 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. And it 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.
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
‘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
If you use library wide-n.el (see MultipleNarrowings), then you can move among multiple restrictions (narrowings) in a buffer. The restrictions are stored in buffer-local variable
‘bmkp-set-restrictions-bookmark’ bookmarks this value for the current buffer. Jumping to such a bookmark restores the saved ring/stack of restrictions.
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.
‘r’in the bookmark-list display (or
‘C-x p r’elsewhere) to edit the name and the target file name (bookmarked location) of a bookmark. You are prompted for the new names.
‘e’in the bookmark-list display (or
‘C-x p E’elsewhere) to edit a complete bookmark – all of its information. You edit the internal EmacsLisp sexp that represents the bookmark record. This is the same internal definition that you see when you use
‘C-u C-h RET’in the bookmark list.
‘E’in the bookmark-list display to edit the bookmark records of all of the marked bookmarks. Again, this means editing their internal Lisp sexps. In particular, this gives you an easy way to edit tags across multiple bookmarks. All of the editing power of Emacs is available.
‘T e’in the bookmark list (or
‘C-x p t e’elsewhere), to edit a bookmark’s tags.
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:
There are many more keys and commands for editing bookmark tags. You can copy tags (
‘C-x p t c’) from one bookmark and paste them to others, either replacing the original tags (
‘C-x p t C-y’) or adding to them (
‘C-x p 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.
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 can be thought of as attributes that define the bookmark: its data. Each such attribute is a cons: a nonempty list or a dotted list.
The car of the attribute is its name (a Lisp symbol). The cdr is its value. What the value can be depends on the attribute – in general it can be any Lisp value (number, string, list, symbol, etc.). An attribute with a null cdr means the same thing as having no such attribute present. For example, having the empty attribute `
(tags)’ is the same as having to
‘tags’ attribute at all.
There is nothing more to it: attributes can be anything you like, provided you provide some code to recognize them and do something with them.
Of course, the types of attributes 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 attribute 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 attributes, in addition to
‘rear-context-string’. You can guess what they are – if not, see the doc string of
A Bookmark+ bookmark typically has some additional attributes that you can also guess. Attributes
‘visits’ are updated automatically each time you access the bookmark.
Some bookmarks have a
‘handler’ attribute 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 p c a’ or
‘C-x p c f’, contain a
‘file-handler’ attribute instead of a
‘handler’ attribute. 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’ attribute, for instance. No big deal – that bookmark no longer has a recognizable target location, but the other bookmarks are still OK.
The most important attribute for Bookmark+ users 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
‘tags’ attribute: `
(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 attributes 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 . ()))’.
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.
‘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
‘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.
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:
‘*Bookmark List*’buffer itself: a bookmark-list bookmark.
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
‘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’ 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
‘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’ 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.)
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.
‘*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.
You can use commands
‘bmkp-url-target-set’, bound by default to
‘C-x p c f’ and
‘C-x p 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
‘u’ are used in key sequences for file and URL bookmarks, respectively.)
If you use Dired+, then you can bookmark all of the marked files 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:
‘M-b’– Bookmark each marked file
‘C-M-B’) – Bookmark each marked file in a bookmark-file that you specify
‘C-M-b’– Bookmark each marked file in a bookmark-file you specify, and create a bookmark for that bookmark-file
Each of these commands bookmarks each of the marked files 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-u C-u’– Use all files in Dired, except directories
‘C-u C-u C-u’– Use all files and dirs, except `
.’ and `
‘C-u C-u C-u C-u’– Use all files and all directories
‘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 p 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.
In a similar way, you can bookmark the file or buffer positions of selected hits in a compilation buffer (including
‘*grep*’) or an
‘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
See also: AutonamedBookmarks, bookmarking occur hits using autonamed bookmarks.
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 p B’ and then
‘C-x p 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:
gsview32.exe’ on the bookmark’s target file if it is PostScript? (extension `
‘browse-url’on the file if it is HTML (extension `
.htm’ or `
‘w32-browser’on the file if the file extension is `
.doc’ (e.g., a Microsoft Word file)
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 p c f’ or
‘C-x p 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 attribute
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
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.
‘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
‘w332-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
REGEXP matches the file extension.
For example, to make a command such as
‘C-x p c a’) automatically bookmark `
*.doc’ files using the associated MS Windows program (typically MS Word), add this entry:
("\\.doc$" . w32-browser).
You can look at an autofile bookmark as just a file wrapper: a way to attach meta information (such as tags) to a file. But you can use an autofile bookmark much as you would use a file.
To create a new autofile bookmark, you can use
‘bmkp-autofile-set’), which is bound by default to
‘C-x p 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 non-directory 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, using different bookmark names. Among other things, this lets you tag the same file in different ways.
You can use
‘C-x j a’ (
‘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,
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
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:
‘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.
‘C-x j C-f’) and
‘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-other-window’. Otherwise, the invoke the associated file handler in
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.
‘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
‘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, 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.)
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 generally as if they were bookmarks. You can choose a file to visit or act on by its name and location, but also by its bookmark metadata.
In particular, you can tag a file – that is, specify tags for its associated autofile bookmark. And you can then visit a file 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 they tag.
‘bmkp-autofile-add-tags’), bound by default to `
C-x p t + a’, prompts you for a set of tags and a file location, and creates or sets the corresponding autofile bookmark. Command
‘bmkp-autofile-remove-tags’), bound by default to
‘C-x p t - a’, similarly lets you remove specified tags from a file.
If you also use library Icicles, then you can act on multiple files during the same command (a multi-command). You can thus all at once tag a set of files the same way, or act on a set of files 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.
If you also use library Dired+ (dired+.el) then you can use `
C-+’ to add tags to the marked files and
‘C--’ to remove tags from them. You can use `
‘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
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 file name. 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
‘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.
‘bmkp-find-file-’ commands are available only for Emacs 22 and later (because they use
‘read-file-name’ with a
`C-x j t f % +’ is
`C-x j t . % +’ is
`C-x j t a % +’ is
`C-x j t C-f % +’ is
‘read-file-name’, so you can browse among all files, up and down the file hierarchy. The completion candidates are file names, not bookmark names.
If you use Icicles, there are similar sets of commands, but they all let you act on multiple files at the same time (multi-commands). For example, you can delete (or byte-compile or…) a set of files according to their tags.
Remember that you can create multiple bookmarks for the same file, 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, even using just autofile bookmarks. See Using Multiple Bookmark Files.
A file bookmark can have any number of tags, and multiple file bookmarks can have the same tag. You can sort, show/hide, or mark files based on their tags.
Bookmark-list views (see 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
~/.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 p 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 `
‘C-h m’ in buffer
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
‘S’ in the bookmark-list display or
‘C-x p 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
‘nil’. And you can toggle this option at any time, using `
M-~’ in the bookmark list (command
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 p l’ (lowercase
‘l’), which is bound to
‘bookmark-load’, and do not use a prefix argument. (Using a prefix argument with
‘C-x p l’ is the same as using
‘C-x p L’: it switches bookmark files.) Here too the default is the name of the last bookmark file that you used.
‘*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
‘C-x p 0’) to create a new, empty bookmark file. If you use
‘C-x p 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 p 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
‘C-x p d’) or, in the bookmark list, using
‘x’ or marking then
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 p L’ (switch) or
‘C-x p 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 p x’, to create a bookmark-file bookmark. Jumping to such a bookmark just loads the bookmark file that it records. With
‘C-u C-x p j project-foo’), jumping switches bookmark files. Without
‘C-u’ it accumulates the loaded bookmarks.
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 that was marked in Dired at the time it was created. Jumping to that bookmark-file bookmark makes those (marked) files 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. `
Bookmark+ enhances the bookmark list (aka the bookmark “menu list”, a misnomer) that is displayed in buffer
‘*Bookmark List*’ when you use
‘C-x p e’ or
‘C-x r l’ (command
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
‘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.
‘C-h m’ in buffer
‘*Bookmark List*’ for more information about the bookmark list, including the following:
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 p 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’ and
‘C-x p t C-h’. Beyond that, the tag-related keys that are more than two keystrokes are organized as follows:
>’ stands for the marked bookmarks
‘*’means AND (set intersection; all)
+’ means OR (set union; some/any)
~’ means NOT (set complement)
‘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.
‘-’ 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 (`
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
C-x p ?’) shows you the tags that belong to a bookmark. With a prefix argument it shows you the full internal form of the tags, that is, the name+value pairs.
‘C-x p t e’) lets you edit a bookmark’s tags.
‘C-x p t l’) lists all tags currently known to Emacs (across all bookmarks).
T +’ (`
C-x p t + b’) adds some tags to a bookmark.
‘C-x p t - b’) removes some tags from a bookmark.
‘C-x p t 0’) removes all tags from a bookmark.
‘C-x p t d’) removes a set of tags from all bookmarks.
In the bookmark list display you can also sort bookmarks according to how they are tagged, even in complex ways. See SortingBookmarks.
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
‘T m * Java RET ide RET RET’, to mark them.
T > + Java IDE Projects RET RET, to tag them.
How would you sort your bookmarks, to show all those tagged both
‘T m * blue RET moon RET RET’, to mark them.
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 `
How would you query-replace the set of files that are tagged with any of the tags
‘gamma’, but are not tagged
‘F S’, to show only the file bookmarks (see FilteringBookmarks, below).
T m + alpha RET beta RET gamma RET RET’, to mark the bookmarks that have at least one of those tags.
T u + blue RET moon RET RET’, to unmark those that are tagged
‘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.
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
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 `
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
‘T m * blue RET moon RET RET’.
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.
% m’ to mark the bookmarks that match a regexp. The entire line in the bookmark list is checked for a match, that is, both the bookmark name and the file name, if shown.
‘U’) to unmark all bookmarks, or all that are marked `
>’, or all that are flagged
‘t’to toggle (swap) marked and unmarked bookmarks: those that are marked become unmarked, and vice versa.
>’ to show only the marked bookmarks or `
<’ to show only the unmarked bookmarks. Repeat to show them all again.
‘I M’etc. to mark only the file bookmarks, Info bookmarks etc. (The first key here is the same as the corresponding filter key, e.g.
‘F’for files – see FilteringBookmarks, below.)
‘O M’to mark the orphaned bookmarks, that is, those whose recorded files have been renamed or deleted. You can then relocate or delete the bookmarks, as appropriate.
You can hide and show different sets of bookmarks in the bookmark list. There are commands to show only the bookmarks of a particular type – e.g.
‘I S’ to show only the Info bookmarks,
‘X S’ to show only the temporary bookmarks. These are, in effect, shortcuts for first marking those bookmarks and then showing only the marked bookmarks (and then unmarking). For example,
‘F S’ is a shortcut for `
F M >’ (and then
You can also filter to show only the bookmarks that match a regexp. There are two ways to do this:
‘P B’(for “pattern”, “bookmark”) and type a regexp. The bookmarks are filtered incrementally, as you type. Only the bookmark name is matched (not the file name). Hit any non-inserting key, such as
‘RET’, to finish defining the pattern. Similarly, hit
‘P F’for bookmarks whose file names match a regexp,
‘P A’for bookmarks whose annotations match a regexp, and
‘P T’for bookmarks with one or more tags that match a regexp. See BookmarkTags, above, for information about tags.
% 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:
.’ – Show all bookmarks.
‘B S’– Show only non-file (e.g. buffer) bookmarks.
‘F S’– Show only file (including directory) bookmarks. With a prefix argument, hide remote-file bookmarks.
‘G S’– Show only Gnus bookmarks.
‘I S’– Show only Info bookmarks.
‘K S’– Show only desKtop bookmarks (see AdditionalTypes).
‘M S’– Show only man-page bookmarks.
‘O S’– Show only omitted bookmarks (see OmittingBookmarks).
‘R S’– Show only bookmarks with region information.
‘V S’– Show only variable-list bookmarks (see variable-list).
‘W S’– Show only W3M bookmarks.
>’ – Toggle showing only marked bookmarks
<’ – Toggle showing only unmarked bookmarks
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.
‘F S’– Show only bookmarks associated with files.
% m’ – Mark those whose names match a particular regexp.
‘R S’– Show only bookmarks that have regions.
‘m’– Mark some of those region bookmarks individually.
.’ – Show all bookmarks.
‘t’– Toggle the marked and unmarked (so unmarked are now marked)
‘D’– Delete 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.
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
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.
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
You can also change directly to one of the main sort orders (without cycling) using `
‘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.
s >’ – Sort marked (`
>’) before unmarked
‘s *’– Sort modified (
‘*’) before unmodified
‘s 0’– Sort by bookmark creation date/time
‘s b’– Sort by last buffer or file access
‘s d’– Sort by last bookmark access date/time
‘s D’– Sort flagged (
‘D’) before unflagged
‘s f d’– Sort by last local file access date/time
‘s f k’– Sort by local file kind: file, symlink, dir
‘s f n’– Sort by file name
‘s f s’– Sort by local file size
‘s f u’– Sort by last local file update (edit) date/time
‘s g’– Sort by Gnus thread: group, article, message.
‘s i’– Sort by Info manual, node, position
‘s k’– Sort by bookmark type (kind)
‘s n’– Sort by bookmark name
‘s t’– Sort tagged (
‘t’) before untagged
‘s v’– Sort by visit frequency
You can reverse 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 (
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
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
‘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 (
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
‘delta’, and then sort according to tag
‘tag2’, which represents the set of tags
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. `
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).
= f M’ and `
= b M’ – mark
= f S’ and `
= b S’ – show (only)
For navigation, the following keys jump to bookmarks for particular files or buffers. (Use
‘C-x 4 j’ for other-window.)
C-x j ,,’ – current buffer
C-x j = f’ and `
C-x j = b’ – specified file(s) or buffer(s)
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 p ,’ opens the bookmark-list display for only those bookmarks. (`
,’ stands generally for “this-buffer” in Bookmark+ key bindings.)
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
‘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.
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:
C-x p :’ (
‘bmkp-choose-navlist-of-type’) – As the set of all bookmarks of a certain type (
‘any’or empty input means use all bookmarks).
‘C-x p B’(
‘bmkp-choose-navlist-from-bookmark-list’) – As the set of all bookmarks corresponding to a bookmark-list bookmark, that is the bookmarks corresponding to a given recorded state of buffer
Each of these lets you choose a set of bookmarks using completion. For `
C-x p :’ you are prompted for the type of bookmark (e.g.
‘C-x p 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:
‘C-x p down’(see Cycling in the Current File/Buffer) then the bookmarks in the current file or buffer are used as the navlist.
‘bookmark-alist’) as the navlist.
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 p : 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 p B’ to define the navlist using a particular bookmark-list bookmark or the current
‘*Bookmark List*’ state, that does not mean that the `
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 p N’ (
So you choose a navigation list. How do you then cycle among its bookmarks?
‘bmkp-previous-bookmark’ cycle to the next and previous bookmark in the navigation list (with wraparound).
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
‘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 has prefix
‘C-x p’. To do this it binds similar commands that can be repeated by simply repeating the key-sequence suffix. These are the keys:
‘C-x p f’,
‘C-x p C-f’,
‘C-x p right’
‘C-x p b’,
‘C-x p C-b’,
‘C-x p 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:
‘C-x p next’ (PageDown key)
‘C-x p 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 `
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 p 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.
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 p down’ and
‘C-x p 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-previous-autonamed-bookmark-repeat’) to handy keys. Otherwise, you can just use the cycling commands without binding them.
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
‘C-x p n’,
‘C-x p C-n’,
‘C-x p down’
‘C-x p p’,
‘C-x p C-p’,
‘C-x p up’
Starting with Emacs 23.3 (Emacs fix for bug #6256), you can also use the mouse wheel to cycle:
‘C-x p’ then just rotate the wheel.
Again, you can bind any keys you want to these commands (e.g.
‘S-f2’). If you do not need to use a prefix key, then bind commands
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
Alternatively, you can use `
C-x p ,’ to display the `
List*’ with only the current file/buffer’s bookmarks, sort them there, and then use
‘C-x p B’ to set the navigation list to
‘CURRENT *Bookmark List*’. In that case, you use the navlist cycling keys (e.g.
‘C-x p f’, not
‘C-x p 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.
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 p 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 autonamed bookmark in buffer `
foo.el’ at position 58356 is `
(You can customize the format of autonamed bookmarks using options
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).
‘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 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 p RET’ is
‘bmkp-toggle-autonamed-bookmark-set/delete’, and it does double duty. If an autonamed bookmark is under the cursor, then
‘C-x p 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 p 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 p 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 p RET’, you can create autonamed bookmarks using these commands:
‘bmkp-set-autonamed-bookmark-at-line’– At a line beginning
‘bmkp-set-autonamed-regexp-buffer’– At buffer matches
‘bmkp-set-autonamed-regexp-region’– At region matches
‘*Occur*’) -- - At
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
(add-hook 'kill-buffer-hook 'bmkp-delete-autonamed-this-buffer-no-confirm) (add-hook 'kill-emacs-hook 'bmkp-delete-autonamed-no-confirm)
Autonamed bookmarks are easy-come-easy-go in the sense that
‘C-x p 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?
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:
‘C-x p 0’ (
‘bmkp-empty-file’) to create a new, empty bookmark file.
‘C-x p L’ (
‘bmkp-switch-bookmark-file-create’) to switch to using that new, empty bookmark file.
‘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 loading 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.
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).
‘bmkp-make-bookmark-savable’prompt you for a bookmark name and then set its temporary/savable status. Command
‘bmkp-toggle-temporary-bookmark’combines these commands, toggling the status for a given bookmark. In the bookmark list, this toggle is bound to
‘C-M-X’. There are also commands in the bookmark-list display to toggle the temporary/savable status of the marked bookmarks (
‘M-X’), to mark the temporary bookmarks (
‘X M’), and to show only the temporary bookmarks (
‘bmkp-autotemp-bookmark-predicates’. It is a list of bookmark predicates – typically type predicates – that define which bookmarks are automatically made temporary whenever they are set. The default value includes the type predicates for autonamed bookmarks:
‘bmkp-autonamed-this-buffer-bookmark-p’. This means that (only) autonamed bookmarks are made temporary whenever they are created or updated. The doc string for the option lists the predefined bookmark type predicates, but you can use any bookmark predicates.
‘bmkp-toggle-autotemp-on-set’, which is bound globally to
‘C-x p x’.
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.
You might or might not find automatic bookmarking useful. The idea is that Emacs sets a bookmark for you automatically, whenever you are idle for a given period of time (option
‘bmkp-auto-idle-bookmark-mode-delay’). Then you can navigate among those bookmarks to visit spots where you spent some time (idly).
How many such automatic bookmarks would you want? And where? Bookmark+ tries to provide some user options that let you get the behavior you want.
In general, you probably do not want such bookmarks to be created too often or too close together. You probably do not care about the names of the bookmarks created, and you do not want to be interrupted to name them. You probably want automatic 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 automatic bookmarks to be temporary (current session only) or highlighted.
‘bmkp-auto-idle-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-global-auto-idle-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 is not enough that the mode be enabled in the buffer.
‘bmkp-auto-idle-bookmark-mode-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. You typically want bookmarks that are created automatically 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.)
‘bmkp-auto-idle-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 the 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-auto-idle-bookmark-mode-set-function’. For example, if automatic bookmarking sets autonamed bookmarks, then
‘bmkp-autotemp-bookmark-predicates’ should include
‘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
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
NOTE: If you use Emacs 20, then by default
‘bmkp-auto-idle-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-auto-idle-bookmark-mode’ is local but there is no global mode,
‘bmkp-global-auto-idle-bookmark-mode’. This is because Emacs 21 does not support
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.
By default, autonamed bookmarks are highlighted differently from non-autonamed bookmarks. Bookmark highlighting uses a style and a face. The available styles are these:
‘Line’– Highlight line of the bookmark position
‘Position’– Highlight character at bookmark position
‘Line Beginning’– Highlight first character on line
‘Left Fringe’– Highlight only the left fringe
Left Fringe + Line’ – Highlight the left fringe and the line
‘Right Fringe’– Highlight only the right fringe
Right Fringe + Line’ – Highlight the right fringe and the line
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 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
H +’ – Set the highlighting for this line’s bookmark
H > +’ – Set the highlighting for the marked bookmarks
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-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.
You can highlight or unhighlight a bookmark or a set of bookmarks on demand.
In the bookmark list (buffer
‘H U’– Highlight, unhighlight this line’s bookmark
H > H’, `
H > U’ – Highlight, unhighlight the marked bookmarks
‘C-x p C-u’– Unhighlight a highlighted bookmark at point or on the same line (in that order)
‘C-x p h’,
‘C-x p u’– Highlight, unhighlight a bookmark in the current buffer (with completion).
‘C-x p H’,
‘C-x p U’– Highlight, unhighlight bookmarks:
‘C-u’: all bookmarks
‘C-u C-u’: navigation-list bookmarks
The default bookmark for
‘C-x p u’ is the same bookmark that is unhighlighted by
‘C-x p 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 p 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:
‘C-u’: prompted for style and face
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:
‘Autonamed bookmarks in buffer’
‘Non-autonamed bookmarks in buffer’
‘All bookmarks in buffer’
None (no automatic highlighting)’ – the default
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.
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 (
‘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:
C-x p =’ – List the bookmarks that are highlighted at point. With a prefix arg, show the full data.
‘C-x j h’,
‘C-x 4 j h’– Jump to a highlighted bookmark. Only highlighted bookmarks are completion candidates.
‘C-x p C-down’,
‘C-x p C-up’– Cycle to the next and previous highlighted bookmark.
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:
‘bmkp-bookmark-set-confirm-overwrite’(prompt for name).
‘C-u’: same as
‘bmkp-bookmark-set-confirm-overwrite’(prompt for name, no bookmark overwrite.
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
‘*Completions*’window according to their bookmark type.
C-M-j . * C-M-j S-TAB’.
^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.
‘M-m’in the minibuffer. You can think of this as similar to using
‘*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’.
C-,’ to cycle among sort orders.
‘C-M-down’, etc.) to get detailed information about the current bookmark candidate.
‘C-u C-M-RET’shows the complete, internal info defining the bookmark. And without doing anything, summary info about the current candidate is available in the mode line of buffer
‘C-down’, etc.) to visit any number of bookmarks. For example, holding down
‘C-down’cycles among the current bookmark candidates, opening each in turn.
‘S-delete’to delete the bookmark named by the current candidate. You can delete any number of bookmarks this way, during a single invocation of a bookmark command.
During file-name completion, you can do any of the following on the fly:
‘C-x a a’.
C-x a +’.
‘C-x a -’.
See Also: Icicles - Bookmark Enhancements.
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
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):
‘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.)
‘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-
‘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-
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.
‘M-x set-variable bmkp-propertize-bookmark-names-flag nil’, to stop using propertized bookmark names.
‘C-x p e’or
‘C-x r l’, to display the bookmark list.
‘g’, to refresh the display.
‘S’, to save the bookmark list.
‘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’. 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:
It has actions for the individual bookmark you point to when you pop it up.
The same menu is available on
It has submenus Icicles (if you use Icicles), Jump To, Mark, Omit, Show, Sort, Tags, Highlight, and Define Command. The Jump To menu itself has a submenu With Tags.
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.
Bookmark+ adds submenu
‘Bookmarked File’ to the vanilla File menu provided by Emacs.
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.
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.
I would like to use bookmarks with version control (ClearCase) where i have multiple views (base directories) with the same files/directory structure. What i would like to do is to define file type bookmarks with relative paths where i can easily change the base directory (e.g. select it from a list or keep it stored in a global variable). Is something like this already possible (and i’ve just not found it)?
I have thought about it a bit and came up with the following ideas:
Actually 3. sounds like it would provide a very flexible way to extend the built-in functionality of bookmark+.
What do you think? – KaiTetzlaff
Hi Kai. Each bookmark associated with a file has a
(filename . "/the/file/name") entry, where the file name is absolute. Take a look at
‘C-h v bookmark-alist’ to get an idea. Since this info is already part of the bookmark, you don’t need to also save such info using tags. And inside every absolute file name (e.g.
‘/a/b/c’) hides a relative file name (e.g.
‘c’)! ;-) All you need to do is abstract from the absolute file names to relative names, and for that you have function
1. I think what you want is a command that (a) collects all bookmarks whose
‘filename’ entries have files whose relative names match some input pattern, then (b) presents these bookmarks as completion candidates and (c) jumps to the chosen bookmark. For example:
(defun bookmark-jump-relative-file (relfile &optional localp) "Jump to a bookmark whose file has relative name RELFILE. With a prefix arg, only local files are candidates." (interactive "sFile: \nP") (setq relfile (file-name-nondirectory relfile)) (bookmark-jump-other-window (bookmark-completing-read "Jump to bookmark" nil (if localp (bmkp-local-file-alist-only) (bmkp-file-alist-only))
2. You can also do something along the lines of what you’re looking for without any coding. You can see all of the bookmarks that have a particular relative file name, and choose among them. In the
‘P F’to show only the bookmarks whose file names match some regexp, which could be the target relative file name – e.g. `
foo.el’ (or `
/foo.el$’ if you’re worried about excluding extra matches in the same line). You can mark all of these bookmarks using
% m’. The regexp for `
% m’ matches the entire line, bookmark name plus file name (if you are not yet showing file names, use
‘M-t’), so use a regexp that also matches the bookmark name (e.g. `
After you’ve marked the bookmarks that have the same relative file name, you can act on that set of bookmarks in various ways. You can save the set or bookmark it (e.g. creating a
‘bookmark-list’ bookmark). Returning to the saved set is like using a multiple-choice command for the files in the set. You can search+replace the marked bookmarks (
‘M-q’). You can open Dired for just those bookmarked files, which can be in different directories (`
M-d >’). After `
M-d >’, you can bookmark that Dired buffer – that’s another way to come back to this set of files.
HTH – DrewAdams
I am finding this very useful, but it would be nice if there was a quicker way to add tags, e.g. similar to org-mode’s C-c C-c C-c method. – JoeBloggs
Can you describe what you envision? – DrewAdams
In org-mode when you press C-c C-c C-c to tag a headline a buffer pops up showing you the already defined tags, with corresponding keys. You then press one of the keys to add the tag, or TAB to define a new tag. Perhaps the effort is not worth it. However, just removing the first prompt that you get after pressing T + would speed things up a bit, since I think most people will be wanting to tag the bookmark at point in this case. – JoeBloggs
I think I understand (but not sure). I think you’re describing a context where the bookmark that is the target of the tag is known/implicit/obvious, and in that context there is no need to prompt users for the bookmark to tag. Is that it?
The command bound to `
T +’ is general, not specific to, say, buffer `
*Bookmark List*”, where, in effect, the current line corresponds to a specific bookmark. But in that case, the current-line’s bookmark is the default value, so you need only hit
‘RET’ to pick it up. I don’t see that as a big thing, I guess, so I don’t think it’s worth trying to take advantage of that specific context. I suspect you disagree. ;-)
Let me know at least if I’ve understood the suggestion: Since in a context like the buffer list it’s predictable that you want to tag the bookmark on the current line, don’t bother to prompt for which bookmark to tag. – DrewAdams
Yes you’ve understood. I set the customization option to prompt for tags when I create a new bookmark which speeds things up a bit.
I like the new highlighting that you’ve added, and I’m wondering if it’s possible to mimic the functionality of VisibleBookmarks, i.e. persistent bookmark highlighting, quick jumping to next/previous bookmark in current buffer, quick editing of bookmark at point. Then I don’t need to use the
*Bookmark List* buffer so often.
Also, is there any way to jump straight to the bookmark position instead of the annotations buffer (leaving the annotations buffer visible)?
I think Bookmark+ offers everything that
bm.el (VisibleBookmarks) offers, and quite a bit more. See these sections for details:
‘C-x p down’(or
up). (To cycle among only highlighted bookmarks, you can use
‘C-x p C-down’. To jump to only a highlighted bookmark, you can use
‘C-x j h’.)
‘C-x p RET’to set/delete.
You can obviously bind short keys to the various commands. All of the commands mentioned are on the keymap
‘bookmark-map’, so you can alternatively just bind that map to some prefix key that is shorter than
‘C-x p’ – that way you bind all of the commands at once.
I don’t understand your question about jumping and annotations. Please give me a recipe/scenario. Jumping is always to a bookmark, not its annotation. Maybe you are looking for option
‘bookmark-automatically-show-annotations’? That’s a standard option, respected also by Bookmark+. If non-
‘nil’, then any associated annotation is displayed, but not if
‘nil’. Bookmark+ behaves the same as vanilla Emacs wrt annotations and jumping.
Let me know if something in the doc is unclear or does not seem to correspond to what you are looking for. I don’t want to repeat explanations here without knowing what is unclear etc. – DrewAdams
1. OK, I found the cycling and autoname commands, but I can’t find any way of altering the annotation and tags without visiting the bookmarks list.
2. Also, the default bookmark in prompts seems to only be set for bookmarks that were created in this session: if I restart emacs and put point at a pre-made bookmark in a buffer, and then issue a command such as
‘bmkp-describe-bookmark’, there is no default bookmark name in the prompt, so I have to remember the name of the bookmark at point.
3. With regard to jumping and annotations, I want to be able to keep the annotation shown, but have point go to the actual bookmark position. At the moment when I jump to a bookmark (with
‘bookmark-automatically-show-annotations’ set to
‘t’), point is placed in the annotations buffer instead of the bookmark position. This also happens when I view annotations from the bookmark list by pressing
‘A’: point moves to the annotations buffer, which is useless since it is read-only anyway.
‘bmkp-specific-files-jump’ don’t work for me: after entering a buffer/file I get prompted for another one and stuck in an infinite loop.
5. I just found another problem; highlighted bookmarks are not always properly marked in the bookmark list. Sometimes I see a purple mark next to them, sometimes not.
1a. Changing an annotation without visiting
‘*Bookmark List*’ — I made
‘bookmark-edit-annotation’ interactive (it is now a command).
1b. Changing a tag without visiting
‘*Bookmark List*’ — I don’t understand the question. You have commands
‘bmkp-set-tag-value-for-navlist’, all of which are available outside
2. Default bookmark — Vanilla Emacs uses
‘bookmark-current-bookmark’, the most recently used bookmark in the same file, as the default. I generally use this also, except in the
‘*Bookmark List*’, where I use the bookmark of the current line as default. And when reading the name of a bookmark that must belong to a particular type, no default is available if the default chosen as just defined is not in the alist.
However, commands that involve highlighted bookmarks generally use a highlighted bookmark on the same line as point as the default (closest one to point), if any, and otherwise the default described above. I just changed
‘bookmark-edit-annotation-mode’) to do use this as well. BTW, starting with Emacs 23 there can be multiple such defaults if there are multiple highlighted bookmarks on the line – use
3. Selection of annotation(s) buffer — I agree about this and had been meaning to fix it for a while. I don’t really use annotations so I hadn’t bothered. (Also, I use
‘pop-up-frames’ on Windows, which means that a new frame gets the focus no matter what.) Should be better now.
bmkp-specific-(buffers|file)-jump’ — Should be fixed now. Thx.
5. Indication of highlighted bookmarks in
‘*Bookmark List*’ — You will need to be more specific (e.g. a recipe). If you mean the one-char pink background indicator, that does not indicate highlighted bookmarks. It indicates bookmarks that have bookmark-highlight override settings (use
‘C-u C-h RET’ to see what the override is). To indicate all highlighted bookmarks you use
‘H S’ or
‘H M’, to show only the highlighted bookmarks and to mark the highlighted bookmarks, respectively.
Thanks for the feedback. Please try the latest. I also updated cycling features and made a few other changes. – DrewAdams
Thanks for the changes. I made a few more changes shown below (but haven’t uploaded them to bookmark+.el).
1a. Great, thanks
1b. OK, I assumed these were only available in the
*Bookmark List* since the keybindings are only defined there.
2. I altered bmkp-default-bookmark-name to return highlighted bookmark at point if available. This is better for me:
(defun bmkp-default-bookmark-name (&optional alist) "Default bookmark name. If in buffer `*Bookmark List*' then the current line's bookmark. Otherwise, the last-used bookmark in the current buffer. Non-nil ALIST means return nil unless the default names a bookmark in ALIST." (let ((name (if (equal (buffer-name (current-buffer)) "*Bookmark List*") (bookmark-bmenu-bookmark) (or (and (fboundp 'bmkp-default-lighted) (bmkp-default-lighted)) bookmark-current-bookmark)))) (when alist (setq name (car (assoc name alist)))) name))
3. I altered bookmark-send-edited-annotation so that after sending annotation, point returns to previous location (previously you had it set to always send you back to the
(defun bookmark-send-edited-annotation () "Use buffer contents as annotation for a bookmark. Lines beginning with `#' are ignored." (interactive) (unless (eq major-mode 'bookmark-edit-annotation-mode) (error "Not in bookmark-edit-annotation-mode")) (goto-char (point-min)) (while (< (point) (point-max)) (if (looking-at "^#") (bookmark-kill-line t) (forward-line 1))) (let ((annotation (buffer-substring-no-properties (point-min) (point-max))) (bookmark bookmark-annotation-name)) (bookmark-set-annotation bookmark annotation) (setq bookmark-alist-modification-count (1+ bookmark-alist-modification-count)) (bookmark-bmenu-surreptitiously-rebuild-list) (kill-buffer-and-window) (bmkp-refresh-menu-list bookmark))) ; So the `a' marker is displayed (updated).
5. OK, I misunderstood the meaning of the indicator. On a related note, is there any way to quickly change the highlighting style of all bookmarks in a buffer at once without going through customize or
6. I’ve written the following functions for the
*Bookmark List* which I find useful. I bind them to
(defun bmkp-bmenu-move-up+describe-this () "Move up to previous bookmark and then describe it." (interactive) (forward-line -1) (bmkp-bmenu-describe-this-bookmark)) (defun bmkp-bmenu-move-down+describe-this () "Move down to next bookmark and then describe it." (interactive) (forward-line 1) (bmkp-bmenu-describe-this-bookmark)) (define-key bookmark-bmenu-mode-map (kbd "<C-up>") 'bmkp-bmenu-move-up+describe-this) (define-key bookmark-bmenu-mode-map (kbd "<C-down>") 'bmkp-bmenu-move-down+describe-this)
Yes, please do not modify the libraries. Instead, post your suggestions (as you did) or mail them to me.
1b. Commands whose names start with
‘bmkp-bmenu’ are for
‘*Bookmark List*’. Commands whose names lack
‘bmenu’ in the prefix are general. This is a vanilla Emacs convention that I have kept.
2. Different users will prefer different behaviors. I’ve added an option for this:
‘bmkp-default-bookmark-name’. It’s default value gives the behavior you prefer.
3. Good catch. I made a similar change. I don’t think it’s a good idea to require confirmation for deleting the buffer and its window, though. I also changed the commands for accessing bookmarks with annotations, so that only annotated bookmarks are completion candidates.
5. No. But how hard is it to visit the bookmark list? I’m open to suggestions, but I don’t see this as very important.
6. Hm. Such commands, with the same bindings, already exist. What am I missing? See `
‘C-down’). Or are you just saying that you prefer to have the description correspond to the current bookmark after the move instead of the current bookmark before the move? – DrewAdams
5. Here’s a couple of functions to do what I want (the second one might be useful for other things):
(defun bmkp-set-lighting-for-bookmarks-in-buffer (buffer style face) "Set the lighting style and face for all bookmarks in BUFFER" (interactive (list (buffer-name) (cdr (assoc (let ((completion-ignore-case t)) (completing-read "Style: " bmkp-light-styles-alist nil t)) bmkp-light-styles-alist)) nil)) (let ((face (and (not (member style '(lfringe rfringe none))) ; No face possible for these. (y-or-n-p "Change face? ") ; Allow nil, for `auto'. (condition-case nil ; Emacs 22+ accepts a default. (read-face-name "Face: " default-face) (wrong-number-of-arguments (read-face-name "Face: "))))) bmks-alist) (dolist (bmk bookmark-alist) (if (bmkp-specific-buffer-p bmk buffer) (progn (add-to-list 'bmks-alist bmk) (bmkp-set-lighting-for-bookmark bmk style face (bmkp-lighting-when bmk))))) (bmkp-light-bookmarks bmks-alist))) (defun bmkp-specific-buffer-p (bookmark buffer) "Return t if BOOKMARK's `buffer-name' is BUFFER. But return nil for bookmarks, such as desktops, that are not really associated with a buffer, even if they have a `buffer-name' entry. It does not matter whether the buffer exists. BOOKMARK is a bookmark name or a bookmark record." (let ((buf (bmkp-get-buffer-name bookmark))) (and buf (string= buf buffer) (not (bmkp-desktop-bookmark-p bookmark)) (not (bmkp-bookmark-file-bookmark-p bookmark)) (not (bmkp-sequence-bookmark-p bookmark)) (not (bmkp-function-bookmark-p bookmark)) (not (bmkp-variable-list-bookmark-p bookmark)))))
6. Yes, I wrote those some time ago and forgot that they were slight alterations of functions you’ve already written. – JoeBloggs
5. I added something similar and a little more general. – DrewAdams
5. Great, but it doesn’t light them immediately. Needs a call to bmkp-light-bookmarks at the end of the function. – JoeBloggs
Not an oversight; I want it to be separate. But I’ve added control via a prefix arg. – DrewAdams
This definitely is an oversight: in
‘bmkp-set-lighting-for-buffer’ you have used
‘bmkp-last-specific-file-alist-only’ when it should be
‘bmkp-last-specific-buffer-alist-only’. – JoeBloggs
Right. Thanks, should be OK now. – DrewAdams
I would like to make bookmarks my homepage. How would I do this? (I use ECB and calling
‘bookmark-bmenu-list’ doesn’t seem to work). – baron
Not sure I understand. Does
‘bookmark-bmenu-list’ work for you in vanilla Emacs (i.e., without loading Bookmark+)?
The first thing to try is removing (e.g. renaming) your bookmarks file. If it works then, then try commenting-out half of the file, then a quarter, etc. until you find the bad bookmark(s). – DrewAdams
Recent changes in bookmark.el (bzr emacs) broke bookmark+, i just see empty list and message “bmkp-bmenu-list-1: Symbol’s function definition is void: bookmark-name-from-full-record” in the minibuffer when calling
‘bookmark-bmenu-list’. – Anonymous
Thanks for the heads-up. That should be fixed now. Emacs Dev, in its infinite wisdom, gratuitously renamed function `
‘bookmark-name-from-record’ – presumably to save 5 chars! Naturally, that breaks any 3rd-party code that uses this very basic function. Sheesh! – DrewAdams
1. is there a source code repo for Bookmark+? It’s somewhat onerous to download 7 files manually.
2. I know you are frame-oriented, but from my perspective, Bookmark+ is the necessary compliment to WorkgroupsForWindows because it allows me to have one tag per workgroup. Maybe I can write a hook to automatically load the bookmark+ bookmarks with the same name as a particular workgroup name. – TerrenceBrannon
2. I’m not familiar with WorkgroupsForWindows, but why not? There is nothing frame-oriented about Bookmark+, BTW. You’re right that I personally use it with frame-oriented code such as OneOnOneEmacs, but Bookmark+ should work fine without such an orientation. If you run into a problem, please let me know. – DrewAdams
I haven’t used bookmarks in Emacs before, and followed a recommendation to use Bookmark+ instead of the stock bookmark library.
I read through this page, but one thing it fails to state clearly is how to actually create a bookmark inside a file. I eventually did figure out the key combination
‘C-x r m’. – akaihola
Yes. This page does not try to be a one-stop description of both Bookmark+ and Emacs bookmarks in general. I already had a link to the BookMarks page (which gives an overview) in the first sentence, but to make things more clear I now point to the Emacs manual for background info about bookmarks. Thanks for the feedback. – DrewAdams
Hello, why don’t you add a tarball to your page with all the files? Downloading each separately is silly. – [[JE?]]
Why don’t you? That would be helpful. While you’re at it, why not periodically post multiple tar balls with different sets of files for Bookmark+: for those users who want all the bells and whistles; for those users who want 75% of them; for those users who want just the bare minimum; etc. I’m sure other users would appreciate your effort.
You might even leverage auto-install-batch-list.el. Here’s another thing you might leverage: https://github.com/emacsmirror/bookmark-plus. And another: http://marmalade-repo.org/packages/bookmark+. Have fun. – DrewAdams
You are an amazing developer, but i think it would be easier for you and of course your users if you can organize your work on some public VC site like github or at least google code. I am particularly interested in your work on dired. Each time I want to update I have to google for dired+plus and then search for all the related files like find-dired+ dired+ sort-dired=menu+ etc, Same story for bookmarks+ and icicles
it would be just so much easier to do
git clone git@github:drewadams/dired+
and then to update just
I know you are using some fancy version control marking of your files (all these automatic version,updates,date insertion - btw, how do you do that?) but public repository might also bring you some contributors in addition to organizing your work.
Sorry, not interested. But I appreciate your taking the time to make the suggestion.
There are plenty of ways to bulk-download a set of files from the wiki, starting with tweaking auto-install-batch-list.el for any set you want. For Icicles the work is already done for you: Icicles - Libraries#BulkIciclesDownload. As mentioned above, you could do the same thing for BookmarkPlus, if you were interested in that. Dired+ has no hard dependencies on any of my libraries, and its only soft-dependency (optional) is for misc-fns.el.
Every user of some of my libraries uses a different subset, no doubt. Some of my libraries can optionally take advantage of others. Whether someone who wants to use one library also wants to use all or some (which?) of the libraries that it might take advantage of is not obvious. So much for prepackaging particular combinations. But it should be trivial to define the set you want using something like auto-install-batch-list.el. Beyond that, there are apparently some mirrors here and there where you can find some of my stuff in the form you prefer (Git repository). They are not necessarily up to date, but the code is there.
I don’t use anything fancy for version control. I don’t even use version control at all for my Emacs files anymore (haven’t for a long time). I use only (1) header2.el and lib-requires.el to update the file header (see AutomaticFileHeaders), and (2)
‘ediff’ to compare and write change logs. – DrewAdams
Cool, header2.el and lib-requires.el where what I was missing so much, thanks a bunch. But I am still not very clear about automatic changelog insertion. Ediff doesn’t seem to have this functionality. Is it that you insert the timestamps and logs by hand?
And also, how about ELPA? Emacs 24 has it by default, it would be really cool to see all your libraries there.
Yes, I insert change logs by hand, after diffing with
‘ediff’ to remind myself about the changes made. It takes a human (IMHO), preferably the same person who made the change and soon after making it, to understand and summarize a change in the best way for others (and self) to read later.
I believe someone else is working on putting Icicles and BookmarkPlus into an ELPA repository somewhere. Dunno when that will be done. – DrewAdams
Hi Drew, when I create a gnus bookmark with gnus-bookmark-set it puts it in Gnus Bookmark List but not Bookmark List. Is there another command to create gnus bookmarks that work with bookmarks+ ? Also is there a command for creating any type of bookmark (e.g. by prompting for type), or do I have to remember the key bindings for each one seperately? If no such function exists could you please tell me the names of all bookmark creation commands so that I can make this function. – JoeBloggs
Hi Joe. I’m no expert on Gnus. I don’t use it. However, for Bookmark+, try using just the usual bookmark-setting command,
‘bookmark-set’, which is bound to
‘C-x p m’,
‘C-x r m’, and
‘C-x p c m’. You should be able to bookmark this way from either a Gnus article buffer or Gnus summary buffer.
The general idea is that for a particular type of buffer or major mode, which has its own kind of bookmark,
‘bookmark-set’ should do the right thing automatically: it should create a bookmark of the proper type. For example, in Dired,
‘C-x p m’ creates a Dired bookmark; in Info,
‘C-x p m’ creates an Info bookmark; etc.
The buffer/mode itself knows how to create a bookmark of the proper type, no matter how complex that might be. For example, for a Dired bookmark,
‘C-x p m’ needs to record the current set of file markings, omissions, etc. When a specific kind of bookmark is created like this, it records a handler of the proper type. The handler for a Dired bookmark reestablishes the markings and file omissions, inserted subdirectories, etc. All of the information needed for that is recorded in the bookmark itself.
If, however, you do want to create a bookmark of a specific type without being in a particular buffer/mode, you can do that using certain Bookmark+ commands (some of which have default key bindings):
bmkp-set-restrictions-bookmark— requires library wide-n.el
HTH – DrewAdams
OK thanks I guess I should’ve checked a bit more carefully first. Btw, your gnus bookmarks only seem to work when the corresponding summary mode is already open. With the bookmarks that come with gnus it will automatically open the correct summary buffer if it’s not already open (and start gnus if not already started). Is there any way of integrating gnus builtin bookmarks with bookmarks plus? – JoeBloggs
Dunno. As I said, I’m no expert on Gnus and I don’t use it. Perhaps you’d like to take a look at the gnus code and propose a patch. Sorry, but this is not a priority for me.
FWIW, the Bookmark+ code for creating and jumping to Gnus bookmarks is essentially the same as the latest (Emacs 24) vanilla Emacs code in
gnus-sum.el, with one minor improvement (no
‘sit-for’ to wait 1 sec if the buffer is not an article buffer).
I have no idea why Gnus apparently has an additional, separate bookmarking facility, or why that is not integrated (yet) with ordinary bookmarks (Bookmark+ or vanilla). Which was your original question, IIUC. Perhaps there is some good reason to keep some Gnus bookmarks separate? dunno.
That said, Bookmark+ should recognize and correctly handle the bookmarks created by the Gnus code (which use handler
‘gnus-summary-bookmark-jump’) – it’s pretty much the same code. I guess the problem seems to be to get your Gnus-code created bookmarks into your standard bookmark file? Try copying one of them into your bookmark file, to see how it’s handled by Bookmark+, as a start.
I can understand your motivation, but please understand that (a) I do not have the time to investigate this and (b) I do not even have Gnus installed (and have no intention of installing it), so implementing and testing something for it in Bookmark+ would be an added chore for me.
For bookmarking alone there are 415 lines of the Gnus code to examine (`
grep bookmark *.el’). And before that, a thorough understanding of Gnus is probably called for, to understand (a) why it treats bookmarking the way it does, and (b) whether and how some of it might profit from Bookmark+ features etc.
I welcome someone else, such as yourself, making such an effort. What’s needed is to spend some time with Gnus and the Gnus bookmarking code. Another possibility might be to interest BastienGuerry in taking a look at Bookmark+ – he apparently wrote
(BTW, for something like this it’s usually a lot easier to follow up by email.) – DrewAdams
I will look into it, cheers. – JoeBloggs
Joe, it just occurred to me that maybe the only problem is that Bookmark+ (and vanilla Emacs
bookmark.el) don’t know about the Gnus bookmark file(s). IOW, maybe there is no problem handling their bookmarks, but you just have to explicitly load their bookmark file(s).
Can you try that, to see? Just use
‘C-x p L’ (
‘bmkp-switch-bookmark-file’ to load such a file (you presumably know where it is located; I don’t). Then try to use its bookmarks, to see if they are handled OK. This should be the first thing to try. Let me know what you find out. Be sure to back up your bookmark file(s) before such experimenting, just in case.
Also, I contacted BastienGuerry by email, who I think wrote the Gnus bookmarks code. He may be able to help. If you want to follow up by email, feel free – that’s probably easier than communicating this way. Thx – DrewAdams
One thing that I needed was to have the All Tags list alphabetically sorted. I think this would be desirable in most cases. If I haven’t missed anything this could be fixed for instance by replacing
(pp-display-expression (bmkp-tags-list (not fullp) current-only-p) "*All Tags")) with
(pp-display-expression (sort (bmkp-tags-list (not fullp) current-only-p) 'string<) "*All Tags")) in the definition of
‘bmkp-list-all-tags’. – AndersJohansson?
Good idea. Done. The code is a bit different, as it needs to be able to (a) handle a prefix arg (full tags) and (b) respect
Thx – DrewAdams
Another thing that would be very useful, at least for me, the way I use Bookmark+ (doing qualitative text analysis by bookmarking and tagging portions of textfiles), is if there was a possibility to show the bookmark list in another way, showing the tags (or the car of a tag) in a column (preferably instead of the filename which isn’t that important for me right now). I don’t know if this is a stupid idea for some reason, but I think this would help whenever there is a need for an overview of the tags associated with a bunch of bookmarks. — AndersJohansson?
I agree that something like that could be useful. But I’m afraid that one will have to go on my wishlist-todo list.
There is also the problem that a list of tags can be long or short, and so can individual tags be long or short, and tags can contain newlines etc. IOW, there is no obvious and easy way to format such info in a column – I would have to come up with something else.
And because the
‘*Bookmark List*’ itself is complex, I would instead probably show bookmarks plus their tags in a separate display – a separate buffer (as is done for
Dunno when/whether I will do something like this, however, so don’t hold your breath.
One workaround to some extent, at least in the sense that it lets you see a set of bookmarks (all of them, if you like) together with their tags, is
‘bmkp-bmenu-edit-marked’. You might at least take a look at that, to see if it’s helpful. Thx – DrewAdams
I understand there are lots of complexities to consider for this. bmkp-bmenu-edit-marked’ actually worked pretty well for me right now. Thanks —AndersJohansson?
I have a problem when create a file-handler bookmark:
(setq-default bmkp-guess-default-handler-for-file-flag t)
When I create this kind of bookmark in the same session, it works perfect; but when I restart emacs and try to activate the same bookmark it doesn’t work (something about a void
--shell-cmd-- symbol). — EgbertoFuentes?
Here is a workaround (code from last May, before I changed it to use
(defun bmkp-default-handler-for-file (filename) "..." (let* ((bmkp-user (bmkp-default-handler-user filename)) (shell-cmd (if (stringp bmkp-user) bmkp-user (and (not bmkp-user) bmkp-guess-default-handler-for-file-flag (or (and (require 'dired-x nil t) (let* ((case-fold-search (or (and (boundp 'dired-guess-shell-case-fold-search) dired-guess-shell-case-fold-search) case-fold-search)) (default (dired-guess-default (list filename)))) (if (consp default) (car default) default))) (and (require 'mailcap nil t) (car (mailcap-file-default-commands (list filename))))))))) (cond ((stringp shell-cmd) `(lambda (bmk) (dired-do-shell-command ',shell-cmd nil ',(list filename)))) ((or (functionp bmkp-user) (and bmkp-user (symbolp bmkp-user))) bmkp-user) (t nil))))
But before trying the workaround, please send me the definition of that bookmark from your bookmark file (you can change any personal info in it; I only need to see the technical definition).
If you can also send me the definition of the bookmark after applying the workaround (you will need to re-create the bookmark, of course), that will help. Please send the info to me by email if you can (see the file header for the address).
And please let me know your Emacs version, using
‘M-x emacs-version’. Thx – DrewAdams
Sounds interesting. Unfortunately, when I tried to give it a quick try, with my setup, I at first saw buffer
‘*One Key*’ but then I tried to resize a frame with the mouse so I could see things better, and everything went blank (all frames), I saw
Entering debugger... in the echo area, and Emacs completely froze. (That was with a recent development snapshot of Emacs 24.) I had to kill Emacs from the OS.
Tried again, this time with Emacs 24.2. This time, when I hit the key to pop up the menu, I got this:
So it looks like you might have a minor problem with a negative value for
‘dif’. The error seems to arise whenever the frame for buffer
‘*One Key*’ would be wider than the frame from which I invoked it. (For me,
‘*One Key*’ is a special-display buffer, so it is shown in a separate, special-display frame.) All of that is just with one-key.el, without one-key-bmkp.el.
Using a wider frame, to avoid the error, and after loading
one-key-bmkp.el, I can bring up the menu OK, but I see nothing there about bookmarks. You might want to add a little more explanation to your instructions.
Also, if I click mouse-1 in the
‘*One Key*’ buffer, I get this error:
"Invalid key sequence: (down-mouse-1 (#<window 38 on *One-Key*> 422 (479 . 48) 24812906 nil 422 (59 . 4) nil (7 . 6) (8 . 14)))"
Anyway, I’m glad to see people using and building upon Bookmark+.
On the case… Btw, if you’re interested in trying it out while I fix those bugs, here’s a howto:
OK, thanks. I’m busy now, but I’ll play with it a bit later. – DrewAdams
Btw, I found a bug in the bmkp-thing-at-point function in bookmark+-1.el I get an error about syntax-table being nil. If you use the common lisp extensions in cl.el I think you could fix it by changing the function signature to:
(defun* bmkp-thing-at-point (thing &optional (syntax-table (syntax-table)))
Should be OK now; thanks. That’s supposed to be the same as
‘icicle-thing-at-point’, but it hadn’t been updated. Avoiding
‘require’s among libraries can have its drawbacks. – DrewAdams
OK, I think I’ve fixed those bugs in OneKey now. Btw, in future to report a bug please use M-x one-key-submit-bug-report, or press <C-f11> in the
Dunno when I’ll get around to trying it out again, but I’ll try to find some time. Thx – DrewAdams
Just to let you know. I spent just a little time with it. I again ran into problems with Emacs hanging etc. The problems are too general & vague for me to be able to report a concrete bug. It does not seem to play well with using separate frames for different buffers. Will try to find time to try it more later. I did look the code over, and it looks interesting. HTH – DrewAdams
OK, I’ve made a few changes so it works better when opened in its own frame now. Still not perfect (help is shown in original frame instead of new frame), but working on it.. I usually just stick to one frame and hadn’t thought about the possibility of multiple frames. Are there any other situations that I may have overlooked? – JoeBloggs
Thanks for those efforts. I’ll have to take a look later – busy now. Thx – DrewAdams