Bookmark: 記錄檔案中的某一定點(或區域)
http://blog.csdn.net/shenyan008/article/details/7577618 http://www.tamabc.com/article/318290.html
原作者已經看不出是誰了。
This page is about package Bookmark+, which enhances vanilla Emacs bookmarks in many ways. For background about Emacs bookmarks, see the following:
- Emacs manual, node ‘Bookmarks’: Bookmarks
- Bookmark Basics, below
- Bookmarks
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.
To report Bookmark+ bugs: Use ‘M-x customize-group bookmark-plus’. Then follow (e.g. click) the link Send Bug Report, which helps you prepare an email to me.
Some basic keys you can use anywhere:
- Bookmark the file you are editing: ‘C-x p m’
- Jump to a bookmark: ‘C-x j j’
- Tag a file (creates an autofile bookmark): `C-x p t + a’
- List/edit your bookmarks: ‘C-x r l’
Some keys you can use in your bookmarks list (from ‘C-x r l’):
- Add/remove some tags to/from a bookmark: `T +’, ‘T -’
- Mark the bookmarks that have particular tags: `T m +’. Hit ‘RET’ to enter each tag you type, then hit ‘RET’ with empty input when done.
- Unmark all bookmarks: ‘M-DEL’ (just like in Dired)
- Toggle marked/unmarked bookmarks: ‘t’
- Dired the marked bookmarks: `M-d >’. Enter a name for the Dired buffer.
Some keys you can use in DiredMode:
- Bookmark the Dired directory, its current markings, etc.: ‘C-x r m’
- Bookmark each of the marked files: ‘M-b’ (you need Dired+ for this)
Bookmark+ is composed of these libraries:
- bookmark+.el – main (driver) library – loads the rest
- bookmark+-mac.el – Lisp macros
- bookmark+-bmu.el – code for the ‘*Bookmark List*’ (‘bookmark-bmenu-mode’)
- bookmark+-1.el – other required code (non-bmenu)
- bookmark+-key.el – key and menu bindings (non-bmenu)
- bookmark+-lit.el – optional code for highlighting bookmark locations
- bookmark+-doc.el – documentation (essentially the same as this wiki page)
- bookmark+-chg.el – change log entries
The main Bookmark+ library is bookmark+.el. The other required libraries are bookmark+-mac.el, bookmark+-bmu.el, bookmark+-1.el, and bookmark+-key.el. If you want to be able to highlight bookmarks then you will also need library bookmark+-lit.el. I recommend that you byte-compile all of the libraries, after loading the source files (in particular, load bookmark+-mac.el).
Put the directory of these libraries in your ‘load-path’ and add this to your init file:
(require ‘bookmark+)
That will load all of the Bookmark+ libraries. If you do not care about bookmark highlighting then simply do not put bookmark+-lit.el in your ‘load-path’.
By default (see option ‘bmkp-crosshairs-flag’), when you visit a bookmark that has no region it is highlighted temporarily using crosshairs, for easy recognition. (This temporary highlighting is independent of the highlighting provided by bookmark+-lit.el.)
For this optional crosshairs feature you also need library crosshairs.el, which in turn requires libraries col-highlight.el, hl-line, hl-line+.el, and vline.el. Library hl-line comes with vanilla Emacs. You also need Emacs 22 or later for this feature.
Besides the EmacsWiki ElispArea, which always has the latest source files for Bookmark+ you can the get Bookmark+ files in the following ways:
- You can download Bookmark+ from MELPA. If you use Emacs 24 or later, you can both download and install it from within Emacs, easily. To do that, you first need to add ‘melpa’ to list ‘package-archives’. Then use ‘M-x list-packages’ and click `bookmark+’ in the list of available packages. 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))
- JonasBernoulli has created a Bookmark+ Git repository here: https://github.com/emacsmirror/bookmark-plus. (Many other EmacsWiki libraries are also mirrored at the same Git hub – see Git repository.)
Standard option ‘bookmark-default-file’ defines the default location of your bookmark file. Bookmark+ does not change the value. You can change the value, of course, either by customizing it (recommended) or using Lisp code (including in your init file).
However, the value of ‘bookmark-default-file’ is used when you load Bookmark+ to initialize some other variables, in particular option ‘bmkp-last-as-first-bookmark-file’ and internal variable ‘bmkp-current-bookmark-file’.
This means that if you modify ‘bookmark-default-file’ in your init file, and you want your new value to be take into account by Bookmark+, then modify it before you load Bookmark+.
Be aware also that another library that you load might, itself, load Bookmark+, in which case you will for the same reason want to load that library after you have modified ‘bookmark-default-file’. An example of this is Icicles, which loads Bookmark+ if Bookmark+ is in your ‘load-path’.
In general, with Bookmark+ I recommend that you simply set option ‘bookmark-default-file’ once and for all at the outset, preferably by customizing it. You can use ‘bmkp-switch-bookmark-file-create’ at any time to switch to a different bookmark file - it is bound to ‘C-x p L’. You can also invoke it in your init file, provided Bookmark+ has already been loaded.
See Also: Using Multiple Bookmark Files
Here is an overview of some of the features that Bookmark+ provides. Some of these are detailed further below.
- 書籤註解 Bookmark Annotations
- 可以用 org mode 為書籤加上任意形式的(外部)註解，如另一個檔案、網址、書籤
- An optional bookmark annotation is user-supplied text that is saved as part of the bookmark. You can use any text you like, and you can use it for any purpose you like. In Bookmark+, the mode for viewing and editing a bookmark annotation is Org mode, by default.
- In addition, Bookmark+ lets you optionally use a separate file, URL, or bookmark to annotate any bookmark. Accessing (“showing”) such an
external annotation visits its destination. So for example, you can use bookmarks to one or more Org files to annotate one or more
bookmarks. The annotation saved with the bookmark itself just specifies the destination. See Bookmark Annotations.
- 標記/分類 Tag
- You can tag bookmarks, a la del.icio.us. In effect, bookmark tags define bookmark sets. A bookmark can have any number of tags, and
- 標記/分類 Tag
multiple bookmarks can have the same tag. You can sort, show/hide, or mark bookmarks based on their tags.
- Bookmark+ tags can be more than just names. They can be full-fledged user-defined attributes, with EmacsLisp objects as their values.
- 檔案書籤
- You can have multiple bookmarks with the same name. This is particularly useful for autofile bookmarks, which are bookmarks that have the
same name as their target files. They give you the effect of using files themselves as bookmarks. In particular, they let you, in effect, tag files. See Autofile Bookmarks and Tagging Files. (In vanilla Emacs you can also, in theory, have multiple bookmarks with the same name. But you cannot really use them in any practical way. Vanilla Emacs cannot distinguish among them: the most recent one shadows all others with the same name.)
- 記錄使用次數
- Bookmarks record the number of times you have visited them and the time of the last visit. You can sort, show/hide, or mark bookmarks
based on this info.
- 複合書籤
- You can combine bookmarks, to make composite, or sequence, bookmarks. Invoking a sequence bookmark invokes each of its component
bookmarks in turn. A component bookmark can itself be a sequence bookmark.
- 區間註解
- You can bookmark a region of text, not just a position. When you jump to a bookmark that records a region, the region is activated (see
option ‘bmkp-use-region’). (Region activation is not supported for Gnus bookmarks.) You can define your own region handler for bookmarks that record regions. (This is in addition to being able to define bookmark handlers.) Use option ‘bmkp-handle-region-function’ for this. As one example, command ‘bmkp-region-jump-narrow-indirect-other-window’ binds the option to a function that narrows the targeted region in a cloned indirect buffer. (You need library narrow-indirect.el for this command.)
- 依上下文重新定位，不易因檔案內容更動而指向錯誤位置
- Bookmarks are relocated better than for vanilla Emacs when the contextual text changes. By default, when you visit a bookmark that
requires relocation, the bookmark is then saved with the new, relocated position information. If you want to turn off this automatic saving, then customize user option ‘bookmark-save-new-location-flag’ to ‘nil’.
- 單一檔案 Autofile bookmarks. You can bookmark a file without visiting it or naming the bookmark. The bookmark name is the same as the file name (non-directory part). You can have multiple such bookmarks with the same name, to bookmark files with the same name but in different directories.
- 目錄列表 Dired bookmarks. You can bookmark a Dired buffer, recording and restoring its ‘ls’ switches, which files are marked, which subdirectories are inserted, and which (sub)directories are hidden.
- 目錄樹 Dired-tree bookmarks. A set of Dired bookmarks that represent a directory hierarchy and are opened together.
- 書籤列表快照 Bookmark-list bookmarks. You can bookmark the current state of buffer ‘*Bookmark List*’ – a list of bookmarks. Jumping to such a bookmark restores the recorded sort order, filter, markings, title, and omit list.
- 書籤檔 Bookmark-file bookmarks. You can bookmark a bookmark file. Jumping to such a bookmark loads the bookmarks in the file.
- 桌面配置書籤 Desktop bookmarks. You can bookmark the current Emacs desktop, as defined by library desktop.el – use command ‘bmkp-set-desktop-bookmark’ (‘C-x p K’). You can “jump” to a desktop bookmark (that is, restore its saved desktop). A desktop includes:
- Some global variables. To exclude variables normally saved, see option ‘bmkp-desktop-no-save-vars’.
- The current set of buffers and their associated files. For each: its mode, point, mark, and some local variables.
If option ‘bmkp-desktop-jump-save-before-flag’ is non-‘nil’, and if the current desktop was made current by jumping to a bookmark, then it is saved before jumping to the next desktop. If you want to save the last desktop jumped to when you quit Emacs, then add ‘bmkp-desktop-save-as-last’ to ‘kill-emacs-hook’.
- Gnus bookmarks. You can bookmark a Gnus article, a URL, a PDF file (DocView), a UNIX manual page (from the output of Emacs command `man’ or `woman’), an image, or a piece of music.
- Non-file (buffer) bookmarks. You can bookmark a buffer that is not associated with a file.
- Function bookmarks. A bookmark can represent a Lisp function, which is invoked when you “jump” to the bookmark.
- 書籤序列 Sequence (composite) bookmarks. A bookmark can represent a sequence of other bookmarks.
- Lisp variable bookmarks. A bookmark can represent a set of variables and their values.
- 模版書籤 Snippet bookmarks. Select some some text and give it a (bookmark) name. Then copy it to the kill ring anytime, in any Emacs session.
- Icicles search-hits bookmarks. (You need library Icicles to use this feature.) During Icicles search you can use `C-x C-M->’ to save the current set of completion candidates (search hits matching your current input) as an Icicles search-hits bookmark. During a later Icicles search you can retrieve those search hits saved in the bookmark, by using `C-x C-M-<’. You can add to (instead of replacing) the current set of hits with the hits retrieved from a bookmark using `C-x C-<’. This is the only way you can “jump” to such a bookmark. See also Bookmarking Icicles Search Hits.
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.
- You can bookmark the file or URL named at point (or any other file or URL), without first visiting it.
- You can bookmark the targets of the hits in a compilation buffer or an ‘occur’ buffer, without first visiting them.
- You can bookmark all of the marked files in Dired at once.
- In the ‘*Bookmark List*’ display, a ‘mouse-3’ popup menu has actions for the individual bookmark that you point to when you click the mouse.
- In the ‘*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.
- The vanilla Bookmarks menu, which is typically a submenu of the menu-bar Edit menu, is modified by adding several items from the `Bookmark+’ menu, including submenus Jump To, Tags, and Highlight.
- Bookmark+ adds two items to the menu bar Edit menu:
- Save the active region text as a bookmark.
- “Jump to” the bookmark to copy the text to the kill ring, so you can then yank it anywhere.
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 “15. Bookmark List Display” .
- 顯示狀態暫存 The last display state is saved (by default), and is restored the next time you show the list. (Tip: Use the bookmark list as your Home page at Emacs startup.)
- You can save the current bookmark-list state at any time and return to it later. There are a few ways to do this, including bookmarking the list itself. See BookmarkListViews.
- 選取 Marking/unmarking is enhanced. It is similar to Dired’s.
- 類別 You can easily mark or show different classes of bookmarks.
- 不同顯示(顯色、字體…)區分書籤類型 Faces distinguish bookmarks by type:
- Info nodes
- Gnus articles
- W3M URLs
- Man pages (from `man’ or `woman’)
- local files with regions
- local files without regions
- local directories
- remote files or directories
- remote files or directories that must be accessed by ‘su’ or ‘sudo’ (‘root’)
- bookmark-list bookmarks
- desktop bookmarks
- function bookmarks
- sequence bookmarks
- variable-list bookmarks
- non-file buffers
- buffers that don’t currently exist
- possibly invalid bookmarks
- 排序 You can sort bookmarks in many ways. You can easily define your own sort orders, even complex ones.
- 搜尋/取代You can regexp-search (‘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).
- You can use `M-d >’ to open Dired for just the local file bookmarks that are marked (`>’).
- windows可以用關聯程式開啟 If you use Emacs on Microsoft Windows, you can open bookmarks according to Windows file associations. (You will also need library w32-browser.el.)
- 名稱自動完成 You can use (lax) completion when you set a bookmark using ‘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.
- You can edit a bookmark: its name and file name/location, its tags, or its complete defining internal Lisp record.
- 狀態行 The mode line shows the number of bookmarks that are marked (`>’), flagged for deletion (‘D’), tagged (‘t’), temporary (‘X’), annotated
(‘a’), and modified (unsaved) (‘*’). It also shows the current sort order. For each of the number indicators (e.g., the number marked):
If the current line has the indicator (e.g. `>’) 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 ‘N’. This feature is available starting with Emacs 24.3. (For prior versions I removed it because Emacs bug #
12867 can cause Emacs to crash.)
- It is easy to recognize modified (i.e., unsaved) bookmarks. They are marked with ‘*’. 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.
- 無效或孤兒書籤 It is easy to recognize orphaned and invalid bookmarks.
- Invalid bookmarks are shown in a special face in the bookmark-list display.
- You can easily mark all of the orphaned bookmarks, that is, those whose recorded files have been renamed or deleted. You can then
relocate or delete those bookmarks.
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.
- Prefix ‘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.
- Prefix ‘C-x p c’ is for setting various kinds of bookmarks.
- Prefixes ‘C-x j’ and ‘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 ‘bookmark-map’.)
- ‘bookmark-map’ – ‘C-x p’
- ‘bmkp-set-map’ – ‘C-x p c’
- ‘bmkp-jump-map’ – ‘C-x j’
- ‘bmkp-jump-other-window-map’ – ‘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.
- Information about individual bookmarks.
- Anywhere in Emacs, `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).
- In the bookmark list, ‘C-h RET’ (or ‘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.el for more information about ‘exiftool’.)
And again, a prefix arg (‘C-u C-h RET’) means show the full (internal) bookmark information. `C-h >’ shows the same information that
‘C-h RET’ shows, but for all of the marked bookmarks, in the current sort order. That is, it describes each of the marked bookmarks.
‘C-down’ and ‘C-up’ move the cursor down and up a line, respectively, but they also show the description of the bookmark
corresponding to the new cursor location. This is a quick way to cycle among bookmark descriptions, in the current sort order.
- General Bookmark+ documentation.
- Anywhere in Emacs, ‘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.)
- In the bookmark list, `?’ and ‘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 ‘M-x describe-mode’.)
- In the ‘bookmark-plus’ group customization buffer (‘M-x customize-group bookmark-plus’), click button ‘Commentary’.
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 bookmark+.el).
See the doc strings of command ‘bookmark-set’ (Bookmark+ version) and options ‘bmkp-new-bookmark-default-names’ and ‘bmkp-default-bookmark-name’.
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:
- 記憶體中 the bookmark list
- 檔案中 the bookmark file
- 緩衝區中 the bookmark-list display (buffer ‘*Bookmark List*’, aka the bookmark “menu list”, a misnomer)
It is important to keep these three straight and understand their differences in practice, in particular, when they do and do not represent the same set of bookmarks.
#1 is in memory. It is the current set of bookmarks. When you add, rename, delete, etc. a bookmark, this list is updated.
#2 is on disk. It is a persistent record of a set of bookmarks.
The bookmark list (#1) is the current value of internal variable ‘bookmark-alist’. The bookmark file (#2) can be anywhere. Its default filename is the value of user option ‘bookmark-default-file’.
The bookmark list is typically initialized from the bookmark file — referred to as loading your bookmarks, but you can also create bookmarks (adding them to the list) without ever saving them to disk.
The bookmark list can be saved to the bookmark file — referred to as saving your bookmarks — either automatically or on demand. But it is not necessarily saved. Even if it has been saved in the past, that does not mean that at any given time the bookmark list corresponds exactly to the bookmark file.
The list and the file can often become out of sync. In an Emacs session, the bookmark list rules. After an Emacs session, the bookmark file rules (it is all there is). You can use ‘C-x 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 ‘bookmark-version-control’ to ‘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.)
User option ‘bookmark-save-flag’ controls whether and how often to automatically save the bookmark list to the bookmark file. You can toggle this option using `M-~’ in the bookmark-list display.
In the bookmark-list display, you can tell whether individual bookmarks have been modified since the last save: they are marked with ‘*’. I believe that this indication is robust and accurate (if not, please report a bug), but a word of caution: do not depend on it. The only way to be sure that your bookmarks have been saved is to save them. ;-)
Is there a way to 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 ‘nil’ and ‘t’, meaning off and on, it can have a value that is the number of bookmark modifications to allow before automatically saving. If the value is 10, for instance, then the 11th modification triggers automatic saving.
But a modification means any change to any bookmark. Typically, you are more interested in considering all of the changes caused by a given command as one modification. Why? Suppose you use a command such as `T > +’ (‘bmkp-bmenu-add-tags-to-marked’), which adds a set of tags to each of the marked bookmarks. Even if there have been no other modifications since you last saved bookmarks, if there are more marked bookmarks than your setting of ‘bookmark-save-flag’ then automatic saving will kick in in the middle of the command. Some of the bookmarks with the added tags will be automatically saved. And that does not give you an opportunity to cancel the changes (e.g., by quitting without saving).
This is the reason for option ‘bmkp-count-multi-mods-as-one-flag’, whose default value is ‘t’, which means count all of a sequence of modifications together as one modification, as far as ‘bookmark-save-flag’ is concerned.
When you jump to a bookmark, you can use completion to specify the bookmark name. ‘bookmark-jump’ and ‘bookmark-jump-other-window’, bound to ‘C-x j j’ and ‘C-x 4 j j’, are general commands. Their completion candidates include all of your bookmarks. With Bookmark+ you can easily have a large number of bookmarks.
To provide more specificity, Bookmark+ provides many different bookmark jump commands. If you want to jump to a bookmark of a specific type, such as Info, you can use a Bookmark+ command that is specific to bookmarks of that type: only those bookmarks are completion candidates.
There are thus type-specific commands: `bmkp-dired-jump’, `bmkp-info-jump’, and so on, bound to `C-x j d’, `C-x j i’, and so on. There are also commands to jump to bookmarks for the current buffer or for particular buffers or files (see Bookmarks for Specific Files or Buffers).
All bookmark jump commands are bound to keys that have the prefix ‘C-x j’. There is an other-window version of most jump commands, and it is bound to the same key as the same-window command, except the prefix is `C-x 4 j’, not ‘C-x j’. For instance, ‘bmkp-dired-jump-other-window’ is bound to ‘C-x j 4 d’.
(In the bookmark-list display, you can use just ‘j’ instead of ‘C-x 4 j’, and just ‘J’ (uppercase) instead of ‘C-x j’.)
More precisely, the bookmark jump commands are on the prefix maps ‘bmkp-jump-map’ and ‘bmkp-jump-other-window-map’, which have the default bindings ‘C-x j’ and ‘C-x 4 j’. You can bind these maps to any keys you like.
If you do not remember the different type-specfic bindings, you can use commands ‘bmkp-jump-to-type’ and ‘bmkp-jump-to-type-other-window’ ( `C-x j :’ and `C-x 4 j :’). They work for any type, prompting you first for the type, then for a bookmark of that type (only).
There are several commands for jumping to a bookmark with tags. The completion candidates can be those bookmarks that have all tags in a given set, some tags in a given set, all tags matching a regexp, or some tags matching a regexp. You are prompted for the set of tags or the regexp to match.
These commands all have the prefix key `C-x j t’. The suffix key is ‘*’ for “all” and `+’ for “some”. The regexp-matching commands precede the suffix key with `%’. For example, `C-x j t % +’ jumps to a bookmark you choose that has one or more tags that match the regexp you input.
There are some type-specific jump commands for bookmarks with tags. The key sequences for these include a key that indicates the bookmark type, after the ‘t’ indicating tags. For example, commands for jumping to a file or directory bookmark having certain tags use the prefix ‘C-x j t f’ (‘f’ for file). Similar commands for autofile bookmarks have prefix ‘C-x j t a’ (‘a’ for autofile).
For example, `C-x j t f % *’ jumps to a file or directory bookmark you choose, where all of its tags match a regexp, and `C-x j t a +’ finds a file tagged with at least one of the tags you input.
In addition to the ordinary autofile “jump” commands, there are ‘find-file’ versions: they read a file name using ‘read-file-name’, instead of completing a bookmark name – see Autofile Bookmarks. These commands are available starting with Emacs 22.
Bookmark names are global. File names are not; that is, the 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 ‘bmkp-file-this-dir-jump’ (`C-x j . f’) offer as completion candidates only bookmarks for files and subdirs in the current directory (‘default-directory’). For tags, there are equivalent commands. For example, `C-x j t . % *’ is the same as `C-x j t f % *’, but the destinations are limited to files in the current directory. All of the “this-dir” file jump commands are bound to the same keys as the general file jump commands, but with `.’ instead of ‘f’.
Remember that Bookmark+ collects lots of commands on only a few predefined prefix keys, primarily as a mnemonic device. Nothing requires you to use the long key sequence `C-x j t f % *’ to visit a file that has a given set of tags. It is expected that you will bind short key sequences to commands that you use often.
The ‘C-x j’ and ‘C-x 4 j’ bindings are global. In addition, in some modes ‘j’ is bound to the corresponding type-specific jump command. For example, in Info mode, ‘j’ is bound to ‘bmkp-info-jump’. (Dired is an exception here: ‘J’ is used instead of ‘j’, since ‘j’ is already taken for ‘dired-goto-file’.) These commands are also added to the mode’s menu-bar menu.
In Dired mode, ‘C-j’ is bound to a special Dired-specific jump command, ‘bmkp-dired-this-dir-jump’, whose destinations all use the current directory (‘default-directory’). The aim of ‘C-j’ is not to change directories but to change to a different set of Dired markings, switches, inserted subdirectories, or hidden subdirectories for the same Dired directory.
In addition to the predefined bookmark types, which you can use as described above, you can define a “type”-specific jump command for any set of bookmarks. That is, you can use any specific set of bookmarks as the completion candidates for a new jump command. Such a set is really only a pseudo-type: the actual bookmarks can each be of any type.
You could use this feature, for example, to define a jump command for the bookmarks that belong to a given project.
One way to define such a command is to first mark the bookmarks that you want to be the completion candidates, then use ‘C-c C-j’ (command ‘bmkp-bmenu-define-jump-marked-command’) in the bookmark list.
The ‘*Bookmark List*’ display defines a set of bookmarks, even without markings. So does each bookmark of type bookmark list, that is, a bookmark corresponding to a particular ‘*Bookmark List*’ display state – see State-Restoring Commands and Bookmarks.
You can capture the set of bookmarks corresponding to a ‘*Bookmark List*’ display for use in navigation, that is, as the current navigation list. Navigation here includes jumping and cycling – see Cycling, Navigation List.
To capture in the navigation list the bookmarks corresponding to either the current ‘*Bookmark List*’ display or a bookmark-list bookmark, use ‘C-x 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’ (‘bmkp-jump-in-navlist’ or ‘bmkp-jump-in-navlist-other-window’).
With Bookmark+ you can bookmark many kinds of Emacs object. Bookmarks record locations – that is their primary purpose. They can also record annotations: general free-text descriptions of your choosing. An annotation is thus metadata that is associated with a bookmark. You can use it for any purpose you like.
Command ‘bookmark-show-annotation’ shows an annotation in read-only mode. You can use ‘C-x C-q’ in the annotation buffer to switch to edit mode (and back again).
You can use command ‘bookmark-edit-annotation’ or ‘bmkp-annotate’ anywhere to edit the annotation for a bookmark. For ‘bookmark-edit-annotation’, you can choose among the bookmarks that already have annotations. With a prefix arg, you can choose any bookmark (and so create an annotation). Using ‘bmkp-annotate’ is the same as using ‘bookmark-edit-annotation’ with a prefix arg.
In the annotation edit buffer, make your changes and then use ‘C-c C-c’ to save the result. Use ‘C-x C-k’ if you do not want to save the changes. You can also use ‘C-x C-q’ and then ‘y’ to confirm reverting the changes.
Non-‘nil’ user option ‘bookmark-automatically-show-annotations’ means that a bookmark’s annotation is popped up whenever you jump to the bookmark. If the non-‘nil’ value is ‘edit’ then the annotation buffer is in edit mode; if it is any other non-‘nil’ value then the buffer is in show (read-only) mode.
In the ‘*Bookmark List*’ display, you can use ‘a’ to show or (with a prefix arg) edit the existing annotation for the bookmark on the current line. (Bookmarks with annotations are marked by an ‘a’ to the left of the bookmark name.)
A bookmark annotation is stored as part of the bookmark itself. For this reason, you typically want to keep the text fairly short. In Bookmark+, the mode for viewing and editing a bookmark annotation is Org mode, by default. (To change the mode used, customize option ‘bmkp-annotation-modes-inherit-from’.)
You can obtain the effect of using longer annotations, and some other advantages as well, by using “external annotations”. These are annotations that are short and serve only as pointers to external files, URLs, or other bookmarks.
Whenever you show the annotation of a bookmark (via ‘a’ in the ‘*Bookmark List*’ display, ‘bookmark-show-annotation’, or ‘bookmark-automatically-show-annotations’) and the annotation is such a pointer, the effect is to visit the destination.
So for example, you can use bookmarks to one or more Org files to annotate (provide metadata for) one or more bookmarks.
You create an external annotation for a bookmark by using one of these forms as the annotation text.
bmkp-annot-url: “FILE” bmkp-annot-url: “URL” bmkp-annot-url: “BOOKMARK”
- FILE is an absolute file name. It is handled by ‘find-file-other-window’.
- URL is a URL. It is handled by ‘browse-url’.
- BOOKMARK is the name of a bookmark in the current bookmark alist.
The double-quote characters are necessary here, so that you can include characters such as ‘SPC’ in the name. The text must be on the first line of the annotation (not counting the commented instruction lines). It can be preceded only by whitespace.
You can include other text in the annotation, after the destination specification, and you can see or edit it when you edit the annotation (e.g., using ‘C-u a’ in buffer `*Bookmark List*’), but it is ignored when the annotation is “shown” (e.g., using ‘a’).
In the ‘*Bookmark List*’ display, ‘M-down’ and ‘M-up’ move the cursor down and up a line, respectively, but they also show the annotation, if any, of the bookmark at the new cursor location.
In addition to annotating bookmarks with arbitrary metadata, Bookmark+ bookmarks can also be tagged, as a way to organize them, which also means as a way to organize the objects that are bookmarked.
By tagging and tag in this context is meant associating keywords or other text with an object, typically in order to classify or characterize it. Tags are metadata about an object. This notion of tagging is sometimes called “delicious” tagging after the Web site www.delicious.com that popularized it (http://en.wikipedia.org/wiki/Delicious_(website)).
Be aware that there is another notion of “tag” associated with Emacs: that involving Emacs TagsFiles, which record the locations of function, variable, etc. definitions in source files. There is no relation between the two notions of “tag”.
A bookmark tag is a string (or a cons whose car is a string – see Bookmark Tags Can Have Values. You can add as many tags as you like to any bookmark, and multiple bookmarks can have the same tag(s). In fact, that’s the whole idea behind using them for organizing.
This feature is unrelated to the fact that bookmarks record locations and are useful for navigating. You can, if you want, use bookmarks to tag files in various ways purely for purposes of organizing them (e.g. into projects), whether or not you ever use the bookmarks as a way to visit them.
For example, if you use Dired+ (library dired+.el), then you can use ‘M-b’ (‘diredp-do-bookmark’) in Dired to create an autofile bookmark for each of the marked files 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.
And if you use libraries Dired+ and Highlight (highlight.el) then autofiles are highlighted specially in Dired, and the highlighting indicates whether the file is tagged.
DrewsEma
By default, you create bookmarks without tags and add tags to them later. If you prefer, you can customize option ‘bmkp-prompt-for-tags-flag’ to non-‘nil’ so that you are prompted to add tags immediately whenever you set (create or update) a bookmark.
There are also some commands, such as ‘bmkp-tag-a-file’ (`C-x p t + a’) and ‘bmkp-untag-a-file’ (‘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. And remember that you can use `C-h >’ to describe all of the marked bookmarks, in the current sort order. The bookmark descriptions include the tags.
When combined with other Bookmark+ commands (e.g. search, query-replace) that apply to the marked bookmarks in the ‘*Bookmark List*’ window, you can really do quite a lot using bookmark tags. Use your imagination!
See Also:
- Bookmark Records: What A Bookmark Looks Like
- Bookmarking the Marked Files in Dired
- Open Bookmarks Using Windows File Associations
- Tag Commands and Keys
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.
Command ‘bmkp-make-function-bookmark’ (‘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 ‘bmkp-set-sequence-bookmark’ (‘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.
Command ‘bmkp-wrap-bookmark-with-last-kbd-macro’ (‘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’. Bookmark ‘my-seq’ need not exist yet, in which case it is created, with the keyboard macro as its only member bookmark.
If the bookmark to add to the sequence is itself a different (existing) sequence bookmark, then its member bookmarks are added to the sequence being updated (or created), either before or after its existing members, according to the prefix arg (which is passed to ‘bmkp-set-sequence-bookmark’).
Command ‘bmkp-bmenu-make-sequence-from-marked’ creates a sequence from the marked bookmarks in the bookmark-list display, in their current order.
If you use library Dired+ then you can use command ‘diredp-do-bookmark-dirs-recursive’ to create a Dired bookmark for the current Dired buffer and each of its marked subdirectories. Each of those subdirectories is handled similarly, and so on, recursively. This command also creates a sequence bookmark that includes all of these Dired bookmarks, so that it represents a tree (hierarchy) of Dired buffers that are opened together. This provides an alternative to inserting all of the relevant subdirectories into the same Dired buffer. With a prefix argument, all of the descendent Dired buffers are included, whether or not they are marked.
A variable-list bookmark saves and restores the values of a set of variables. Command ‘bmkp-set-variable-list-bookmark’ prompts you for the variables to include in the list and then sets the bookmark. Command ‘bmkp-jump-variable-list’ (‘C-x j v’) restores the recorded variable values for the bookmark’s buffer. You can also create variable-list bookmarks non-interactively, using function ‘bmkp-create-variable-list-bookmark’.
If you use library zones.el (see Zones and MultipleNarrowings), then you can move among multiple restrictions (narrowings) in a buffer. The restrictions are stored in buffer-local variable ‘zz-izones’. Command ‘bmkp-set-izones-bookmark’ bookmarks this value for the current buffer. Jumping to such a bookmark restores the saved ring/stack of restrictions.
In vanilla Emacs, you can edit the annotation associated with a bookmark. And you can rename a bookmark. But that is all. There is no easy way to really edit a bookmark.
With Bookmark+:
- You can use ‘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.
- You can use ‘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.
- You can use ‘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.
- You can use ‘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: ‘C-x k’.)
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 are properties: key+value pairs that define the bookmark data. Each such pair is a cons: a nonempty list or a dotted list.
The car of the property is its name (a Lisp symbol). The cdr is its value. What the value can be depends on the property – in general it can be any Lisp value (number, string, list, symbol, etc.). A property with a null cdr means the same thing as having no such property present. For example, having the empty property `(tags)’ is the same as having no ‘tags’ property at all.
There is nothing more to it: properties can be anything you like, provided you provide some code to recognize them and do something with them.
Of course, the types of properties you use most (maybe always) are predefined, and the vanilla bookmark.el code and the Bookmark+ code recognize and use them. The most important and most typical property is this: `(filename . “/some/file/name.txt”)’, that is, a cons whose car is the symbol ‘filename’ and whose cdr is the name (a string) of the bookmarked file.
With that in mind, you can see that renaming a bookmark just means changing the string that is its car. And relocating a bookmark just means changing the string that is its ‘filename’ – e.g., from `(filename . “/home/foo.el”)’ to `(filename . “/some/other.xml”)’.
If you already have a bookmark file, typically `~/.emacs.bmk’, take a look at the bookmark records in it. A typical bookmark also has these properties, in addition to ‘filename’: ‘position’, ‘front-context-string’, and ‘rear-context-string’. You can guess what they are – if not, see the doc string of ‘bookmark-alist’.
A Bookmark+ bookmark typically has some additional properties that you can also guess. Properties ‘time’ and ‘visits’ are updated automatically each time you access the bookmark.
Some bookmarks have a ‘handler’ property whose value is a function that “jumps” to the bookmark “location”. I put those two terms in quotes here because a handler is really just any function – it can do anything you like, and there need not be any associated location.
Some Bookmark+ bookmarks, including autofile bookmarks, just “jump” to a file. The position in the file is unimportant, and “jumping” does not necessarily mean visiting the file with Emacs. In effect, such bookmarks are just wrappers around the file, letting you get the advantage of Bookmark+ features (tags etc.) for a file. Such bookmarks, which you can create using ‘C-x p c a’ or ‘C-x p c f’, contain a ‘file-handler’ property instead of a ‘handler’ property. The difference between the two is that the ‘file-handler’ value is a function (Lisp function or shell command) to be applied to the file, not to the bookmark.
Remember: A bookmark is just a persistent bit of information, typically meta-information about a file and a position in that file.
I’m mentioning all of this to make the point that you cannot really hurt anything if you edit a bookmark record and you mess things up. The worst you can do is mess up all of your bookmarks by making the file unreadable as Lisp data. (It’s always a good idea to back up your bookmark file from time to time.)
And if each bookmark record after you edit it is a cons with a string car then your bookmarks are generally OK, even if you might have ruined the details of one or two of them. Suppose you somehow mistakenly delete the ‘a’ in a ‘filename’ property, for instance. No big deal – that bookmark no longer has a recognizable target location, but the other bookmarks are still OK.
The most important property for Bookmark+ users (aside from ‘filename’) is probably ‘tags’. Its value (the cdr) is a list of strings or conses – the bookmark’s tags. When you create a tag, it is typically a string (just its name) – e.g. “blue”. If you then give it a value as well, it becomes a cons with that string (the name) as car and the value as cdr – e.g. `(“blue” . 42)’ or `(“blue” moonbeam 42)’ – here the cdr is the list `(moonbeam 42)’. Here is an example of a ‘tags’ property: `(tags “hegel” (“blue” . honeypot) “darwin”)’. Most of the time you will use strings as tags. See also Bookmark Tags Can Have Values.
When you edit bookmark records, just try to stay away from changing any properties that you are not familiar with. And make sure that when you’re done you have a proper Lisp list (open parens closed etc.). If you’ve never played with Lisp before, do not panic.
Be aware if you see dots (`.’) that they are important, and they must be surrounded by whitespace: ` . ’. The amount of whitespace never matters in Lisp (except inside a string etc.).
Such a dot just separates the car of a cons from its cdr. (What’s a cons? Just a car with a cdr!) If the cdr is a list then we typically drop the dot and the list’s parens: We write `(b)’ instead of `(b . ())’ and `(a b)’ instead of `(a . (b))’ or `(a . (b . ()))’.
Finally, remember that when you set an existing bookmark again, e.g., you use ‘C-x r m’ and provide the name of an existing bookmark, the existing properties are generally lost. Some are automatically updated. Any that you might have added by editing are lost, and any that are provided by default by the bookmark handler are replaced. The only exceptions to this are the properties listed in option ‘bmkp-properties-to-keep’, which by default means properties ‘tags’ and ‘annotation’. Any existing tags and annotation are preserved when you update a bookmark.
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.
If option ‘bmkp-bmenu-state-file’ is non-‘nil’, which it is by default, then Bookmark+ remembers the last state of the bookmark list when you quit it or you quit Emacs, and it restores that state when you show the list again (which could be in the next Emacs session). You can think of this feature as your Home page for bookmarks, giving you a stepping stone to the files and directories you use most.
If, for example, when you quit the bookmark list you are showing only bookmarks to Info nodes and UNIX manual pages, sorted in a particular way, and with some of them marked with `>’ for particular processing, then the next time you open the list the same state is restored: the same set of bookmarks is shown, in the same order, with the same markings. Deletion flags (‘D’) and modification indicators (‘*’) are purposefully not saved as part of the display state — they are lost when you quit the display.
You can turn off this automatic bookmark-list display state saving, if you want, by customizing option ‘bmkp-bmenu-state-file’ to ‘nil’. And you can toggle this option at any time, using `C-M-~’ in the bookmark list (command ‘bmkp-toggle-saving-menu-list-state’). In particular, if you want your next visit to the bookmark list to start out with a previously recorded state instead of the current state, just hit `C-M-~’ before quitting the bookmark list.
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:
- Create a bookmark for the ‘*Bookmark List*’ buffer itself: a bookmark-list bookmark.
- Define a command that restores the bookmark-list state.
When you use ‘C-x r m’ (‘bmkp-bookmark-set-confirm-overwrite’) in buffer ‘*Bookmark List*’ to create a bookmark-list bookmark, the current sort order, filter, regexp pattern, title, and omit list are saved as part of the bookmark. (These concepts are described below — see BookmarkListDisplay.) Jumping to such a bookmark restores all of these.
Alternatively, you can define a command that does the same thing, but without creating another bookmark – use ‘C-c C-c’ (‘bmkp-bmenu-define-command’) in the bookmark list to do this. You are prompted for the name of the new command. Use the command anytime (including in another Emacs session) to restore the bookmark list.
Define any number of such commands for the views you use. The file for saving the definitions (see option ‘bmkp-bmenu-commands-file’) is never overwritten, so you can also add other code to it manually, if you want. The file is read the first time the bookmark list is displayed in a given Emacs session.
The state that is saved and restored using a bookmark-list bookmark or a command defined using ‘c’ is only a partial state. The current set of markings and some other information are not saved, in order to save disk space and save/restore time.
Sometimes, however, you really want to save the entire bookmark-list state, creating a full snapshot. You can use ‘C-C’ (aka ‘C-c C-S-c’, ‘bmkp-bmenu-define-full-snapshot-command’) to do that. This defines a command that restores the bookmark list completely. That is the same thing that happens automatically (by default) whenever you quit the bookmark list (or Emacs), but defining snapshot commands lets you have multiple saved states and switch to them at will.
Be aware, however, that full-snapshot command definitions can be quite large, since they each contain a copy of the current bookmark list and any accessory lists (hidden and marked bookmarks etc.).
Whether you use ‘c’ or ‘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:
- 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.
- In Dired, you mark certain files and then bookmark all (each) of them, in one operation.
- In a compilation buffer (e.g. ‘*grep*’, ‘*compile*’) or an occur or multi-occur buffer (‘*Occur*’), you bookmark one or more of the hits.
Such a bookmark takes you to the appropriate position in the target file or buffer.
- 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-file-target-set’ and ‘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 ‘f’ and ‘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-S-b’ (aka ‘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 ‘occur’ or ‘multi-occur’ buffer.
‘C-c C-b’ in such a buffer bookmarks the target of the hit at point. ‘C-c C-M-b’ bookmarks the target of each hit in the buffer.
‘C-c C-M-b’ in these buffers is thus similar to ‘M-b’ in a Dired buffer. Unlike Dired, however, there is no way to mark such hits. Every hit is bookmarked.
Nevertheless, you can get the same effect. Just use ‘C-x C-q’ to make the buffer writable (e.g. temporarily), and then remove any hits that you do not want to bookmark. You can remove hits anyway you like, including by ‘C-k’ and by regexp (‘M-x flush-lines’ or ‘M-x keep-lines’).
See also: AutonamedBookmarks, bookmarking occur hits using autonamed bookmarks.
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:
- shell command `gsview32.exe’ on the bookmark’s target file if it is PostScript (extension `.ps’)
- EmacsLisp function ‘browse-url’ on the file if it is HTML (extension `.htm’ or `.html’)
- EmacsLisp function ‘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 property ‘file-handler’ (not ‘handler’).
If you use Microsoft Windows there is no need to define new bookmark types and handlers, if the action you want is the one that Windows associates with the file. You already have a set of file/program associations, and Bookmark+ recognizes these as alternative handlers.
You can thus take advantage of Windows file associations to open bookmarks for files of all kinds. To do this, you also need library w32-browser.el. In the bookmark list, the following keys are bound to commands that open bookmarks using the associated Windows ‘Open’ applications:
- ‘M-RET’ – ‘bmkp-bmenu-w32-open’
- ‘M-mouse-2’ – ‘bmkp-bmenu-w32-open-with-mouse’
- ‘M-o’ – ‘bmkp-bmenu-w32-jump-to-marked’
Windows file associations are always available to you, in addition to any other file associations that you define using ‘bmkp-default-handlers-for-file-types’ (see Bookmarking Files You Cannot Visit with Emacs).
You can thus have two different programs associated with the same kind of file. Your MS Windows file association for PostScript might, for example, use Adobe Distiller to create a PDF file from PostScript, while your ‘bmkp-default-handlers-for-file-types’ association for Postcript might use GhostView to display it directly.
Besides using ‘M-RET’ etc. in buffer ‘*Bookmark List*’, if in ‘bmkp-default-handlers-for-file-types’ you register ‘w32-browser’ as the association to use for a given file pattern, then you can use command ‘bmkp-w32-browser-jump’ (not bound, by default) anywhere to open a bookmark whose file name matches that pattern, using its Windows file-association program.
You can also specify ‘w32-browser’ as the bookmark “type” when you use command ‘bmkp-jump-to-type’ (`C-x j :’). Either of these approaches gives you a way to use completion to choose a bookmark to open using a Windows file association.
Specifying such an association in ‘bmkp-default-handlers-for-file-types’ means that bookmarks for such a file will have a ‘file-handler’ value of ‘w32-browser’, to “jump” to (i.e., open) the file.
To set up a given file extension for use this way, add an entry (REGEXP . w32-browser) to option ‘bmkp-default-handlers-for-file-types’, where REGEXP matches the file extension.
For example, to make a command such as ‘bmkp-bookmark-a-file’ (‘C-x p c a’) automatically bookmark `*.doc’ files using the associated MS Windows program (typically MS Word), add this entry: (“\.doc$” . w32-browser).
User option ‘bmkp-default-handlers-for-file-types’ (see Bookmarking Files That You Cannot Visit with Emacs”) gives you a way to associate a file type, as determined by the file name (typically its extension) with a default file action. This is like MS Windows file associations, but it is specific to Emacs and Bookmark+. And it is useful for more than just bookmarks.
Commands ‘bmkp-find-file’ (‘C-x j C-f’) and ‘bmkp-find-file-other-window’ (‘C-x 4 j C-f’) take advantage of this association to open files. If a file name matches no pattern in ‘bmkp-default-handlers-for-file-types’ then these commands act like ‘find-file’ and ‘find-file-other-window’. Otherwise, the invoke the associated file handler in ‘bmkp-default-handlers-for-file-types’.
Invoking the handler is just what the ordinary autofile jump commands (e.g. ‘C-x j a’) do. But ‘bmkp-find-file’ is different in a couple of ways.
Like vanilla ‘find-file’ (‘C-x C-f’), ‘C-x j C-f’ and ‘C-x 4 j C-f’ use ‘read-file-name’ to prompt you for the file name. The completion candidates are the names of all of the files
in the current directory (‘default-directory’), that is, the directory of your current minibuffer input. This includes the names of any autofile bookmarks in the same directory. And like ‘C-x C-f’ you can change directory, navigating up and down the file hierarchy. In sum, these commands are file-aware.
The ordinary autofile jump commands on the other hand use ‘completing-read’ to complete your input against all autofile bookmark
names, regardless of directory. And since the bookmark names reflect only the relative file names, it is not so easy to distinguish two autofiles with the same name but in different directories. (Icicles can help here, BTW.)
There is a ‘bmkp-find-file-’ command that corresponds to each ‘bmkp-autofile-’ command. For example, ‘bmkp-find-file-some-tags-regexp’ (`C-x j t C-f % +’) corresponds to ‘bmkp-autofile-some-tags-regexp-jump’ (`C-x j t a % +’). All ‘bmkp-find-file’ commands use `C-f’ in their key bindings, as a reminder of their reading file names a la ‘find-file’.
But whereas ‘C-x j C-f’ and ‘C-x 4 j C-f’ let you access any file, the other ‘bmkp-find-file-’ commands, which find files that have certain tags, provide only autofiles as completion candidates. That’s obvious, since files are tagged by bookmarking them.
You can thus use the ‘C-f’ commands to take advantage of file-action associations that you define. But if you want to associate metadata (e.g. tags) with files, 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.)
An autofile bookmark , or just an autofile , is a bookmark that uses the non-directory part of its file name as its bookmark name.
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-bookmark-a-file’ (aka ‘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’ (‘bmkp-autofile-jump’) or ‘C-x 4 j a’ (‘bmkp-autofile-jump-other-window’) to visit an autofile bookmark. And there are commands for visiting an autofile that is tagged in certain ways. For example, ‘bmkp-autofile-some-tags-regexp-jump’ (`C-x j t a % +’) jumps to an autofile bookmark that has at least one tag matching a given regexp. See Tagging Files.
You can create autofiles automatically whenever you use an Emacs file-cache command, by customizing user option ‘bmkp-autofile-filecache’.
This optional bookmark creation can replace adding the file to the cache, or it can be in addition to caching the file. This is done by advising command ‘file-cache-add-file’, which means that it affects also the other Emacs file-cache commands that use that function, directly or indirectly:
- ‘file-cache-add-directory’
- ‘file-cache-add-directory-list’
- ‘file-cache-add-directory-recursively’
- ‘file-cache-add-directory-using-find’
- ‘file-cache-add-directory-using-locate’
- ‘file-cache-add-file-list’
See FileNameCache and the Emacs manual, node `File Name Cache’.
Finally, if you use libraries Dired+ and Highlight (highlight.el) then autofiles are highlighted specially in Dired, and the highlighting indicates whether the file is tagged. Here is a screenshot:
DrewsEma
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.
Command ‘bmkp-tag-a-file’ (aka ‘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-untag-a-file’ (aka ‘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-+’ and ‘C-M–’ to do the same thing for the current file. You can also use items from the Dired menus to do these things.
Bookmark+ provides two kinds of command for visiting files associated with bookmarks that have tags.
The first kind uses bookmarks directly: you choose a bookmark name, not a file name, but the candidates are only file and directory bookmarks. These commands have the prefix ‘bmkp-file-’ or ‘bmkp-autofile-’.
As a special case, commands with the prefix ‘bmkp-file-this-dir-’ limit the choices to bookmarks for files and subdirectories of the current directory. By default, the commands across all directories are on prefix key ‘C-x j t f’, and those for the current directory only are on prefix key `C-x j t .’. See Different Types of Jump Commands for more about these commands.
The second kind of command is for visiting tagged files, that is, autofile bookmarksjust like the commands with prefix ‘bmkp-autofile-’. However, these commands do not handle the bookmark as such, but only its 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 ‘find-file’ (‘C-x C-f’). Like ‘find-file’, they use ‘read-file-name’ to read the bookmark’s file name, instead of using ‘completing-read’ to read the bookmark name.
Yes, for an autofile bookmark the bookmark name and the (relative) file name are the same. But ‘read-file-name’ is file-aware, and lets you browse up and down the directory hierarchy.
The ‘bmkp-find-file-’ commands are available only for Emacs 22 and later (because they use ‘read-file-name’ with a PREDICATE argument).
For example:
`C-x j t f % +’ is ‘bmkp-file-some-tags-regexp-jump’
`C-x j t . % +’ is ‘bmkp-file-this-dir-some-tags-regexp-jump’
`C-x j t a % +’ is ‘bmkp-autofile-some-tags-regexp-jump’
`C-x j t C-f % +’ is ‘bmkp-find-file-some-tags-regexp’
- The first of these visits any file bookmark that has at least one tag among the tags you specify, and you choose among bookmark names. The files can be in any directories.
- The second is similar to the first, but only bookmarks for files in the current directory are completion candidates.
- The third is similar to the first, but only autofile bookmarks are completion candidates.
- The fourth is similar to the third regarding tags, but it uses ‘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 ‘bookmark-default-file’ (`~/.emacs.bmk’, by default).
If you use only one bookmark file then you never need to load or save it manually. Emacs does that for you automatically.
But you can have multiple bookmark files if you want, and at any time you can change the bookmark file that is current. To do that, use ‘C-x 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 `?’ and ‘C-h m’ in buffer ‘*Bookmark List*’.
When you switch to another bookmark file, the default choice for the file to switch to is the last bookmark file you used (in the same session). So it is trivial to toggle back and forth between two bookmark files: just hit ‘RET’ to accept the default.
When bookmarks are saved automatically, or when you save them using ‘bookmark-save’ (‘S’ in the bookmark-list display or ‘C-x 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 ‘bookmark-save-flag’ to ‘nil’. And you can toggle this option at any time, using `M-~’ in the bookmark list (command ‘bmkp-toggle-saving-bookmark-file’).
Besides using multiple bookmark files as alternatives, you can combine them, using them as component bookmark subsets (like modules). To do that, use command ‘C-x 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.
In the ‘*Bookmark List*’ display you can use ‘M-l’ to load all of the bookmark files corresponding to the marked bookmark-file bookmarks, in the order in which they are displayed. Any non bookmark-file bookmarks that are marked are ignored. Before loading, if any of your currently loaded bookmarks have been modified then you are asked if you want to save them first, before loading the others.
After loading, to avoid confusion and possible mistakes, automatic saving to the current bookmark file is turned off. You can always use `M-~’ to turn it back on again. And remember that, as long as you have not saved bookmarks after loading, you can always use ‘C-u g’ to revert to the bookmarks saved in the bookmark file.
To create additional bookmark files, to use either as alternatives or as components, you can either copy an existing bookmark file or use ‘bmkp-empty-file’ (‘C-x 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 ‘bookmark-delete’ (‘C-x p d’) or, in the bookmark list, using ‘d’ plus ‘x’ or marking then ‘D’.
Deleting bookmarks from a bookmark file is one way of editing it. Another is to copy or move bookmarks from one bookmark file to another. In the bookmark-list display, you can copy or move the marked bookmarks (or the current bookmark, if none are marked) from the current bookmark file to another that you name, using `Y > +’ (‘bmkp-bmenu-copy-marked-to-bookmark-file’) and `Y > -’ (‘bmkp-bmenu-move-marked-to-bookmark-file’), respectively. And you can use `Y > 0’ (‘bmkp-bmenu-create-bookmark-file-from-marked’) to create a new bookmark file by copying the marked bookmarks. With a prefix argument, `Y > 0’ creates also a bookmark-file bookmark.
NOTE:
Unlike the other ways of organizing bookmarks into sets (tags, bookmark-list bookmarks, etc.) bookmark files represent physical, not logical, groupings of bookmarks. A bookmark file contains complete bookmark records. If you copy a bookmark from one bookmark file to another, the copy is an independent bookmark: it has no relation to the bookmark it was copied from. Changes to the copy or the bookmark it was copied from do not affect each other. This means that to use bookmark files for organizing bookmarks you will typically move, not copy, bookmarks between them (or copy and later delete). Remember that you can load multiple bookmark files to access their bookmarks together in a session. Think of your bookmark files as independent modules that you can combine.
See Also: Bookmark+ Load Order and Option `bookmark-default-file’.
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 y’, to create a bookmark-file bookmark. Jumping to such a bookmark just loads the bookmark file that it records. With ‘C-u’ (e.g. ‘C-u C-x j y project-foo’), jumping switches bookmark files. Without ‘C-u’ it accumulates the loaded bookmarks.
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. `~/.emacs.bmk’).
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 ‘bookmark-bmenu-list’).
At the top of the bookmark-list display is this header information:
- The bookmark file used currently. This is important because Bookmark+ makes it easy for you to have multiple bookmark files and switch among them.
- A title that describes the kinds of bookmarks listed, that is, it reflects athe current filtering, if any.
For example, this header indicates that the current bookmark file is c:/.emacs.bmk and only file and directory bookmarks are shown:
Bookmark file: c:/.emacs.bmk
File and Directory Bookmarks
(Bookmark+ does not use the sliding header line of vanilla Emacs 24+, which means that option ‘bookmark-bmenu-use-header-line’ has no effect. You do not need to see ‘Bookmark’ and ‘File’ column headers as you scroll.)
Bookmarks are highlighted to indicate their type. You can mark and unmark bookmarks, show or hide bookmarks of particular types, and more. Bookmarks that have tags are marked with a ‘t’. Bookmarks that have an annotation are marked with an ‘a’ (not with a ‘*’ as in vanilla bookmark.el). Bookmarks that have been modified since the last save of the bookmark file are marked with a ‘*’. Bookmarks that have bookmark-highlight override settings (see DefiningHowtoHighlight) are marked with a one-character pink background.
Use `?’ or ‘C-h m’ in buffer ‘*Bookmark List*’ for more information about the bookmark list, including the following:
- The current status of sorting, filtering, and marking.
- A legend for the faces used for different bookmark types.
Bookmark visiting (jumping) commands are globally on prefix keys ‘C-x j’ and ‘C-x 4 j’. In the bookmark-list display they are additionally on ‘j’ (other window) and ‘J’ (same window). In addition, `j >’ is bound to ‘bmkp-bmenu-jump-to-marked’, which jumps to each of the marked bookmarks in other windows.
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’, ‘C-x p t C-h’, and `C-h >’ (which describes the marked bookmarks). Beyond that, the tag-related keys that are more than two keystrokes are organized as follows:
- They all have the prefix key ‘T’.
- ‘m’ means mark
- ‘u’ means unmark
- `>’ stands for the marked bookmarks
- ‘*’ means AND (set intersection; all)
- `+’ means OR (set union; some/any)
- `~’ means NOT (set complement)
The key ‘T m *’, for instance, marks (‘m’) the bookmarks that are tagged with all (‘*’ = AND) of a given set of tags. It prompts you for one or more tags that the bookmarks must have, and it marks all bookmarks that have all of the tags you enter.
The key `T u ~ +’ unmarks (‘u’) the bookmarks that do not (`~’) have any (`+’ = OR) of the tags you specify. And so on. The marking and unmarking commands for tags compare the tags a bookmark has with tags that you enter. Any bookmarks that have no tags are ignored – they are neither marked nor unmarked by these commands.
`+’ and ‘-’ can also mean add and remove tags, respectively, and `>’ stands for the marked bookmarks. So `T > +’ adds (`+’) one or more tags to each of the marked (`>’) bookmarks.
In general, the tag-related commands let you enter a set of tags, one at a time. Thus, instead of having a command that adds a single tag to the current bookmark, you have a command that adds any number of tags to it. To add just a single tag, hit ‘RET’ twice: once to enter the tag, and once again to indicate that it is the last (i.e., the only) one.
If you just hit ‘RET’ immediately, specifying an empty set of tags, then each of the commands does something appropriate. For ‘T m *’, for instance, an empty list of tags means to mark (only) the bookmarks that have some tags (any at all).
Finally, for the marking/unmarking tags commands, a prefix argument flips the sense of the command, in this way:
- “some are” → “some are NOT”, i.e., “not all are” (and vice versa)
- “all are” → “all are NOT”, i.e., “none are” (and vice versa)
In other words:
C-u T m * = T m ~ + (all are NOT = not some are) C-u T m ~ + = T m * (not some are NOT = all are) C-u T m + = T m ~ * (some are NOT = not all are) C-u T m ~ * = T m + (not all are NOT = some are)
You’ll figure it out ;-).
Other important keys pertaining to tags (the keys in parentheses work in any buffer, not just buffer ‘*Bookmark List*’):
- ‘C-h RET’ (`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-h >’ describes all of the marked bookmarks, in the current sort order. The descriptions include the tags. (You can use ‘T m * RET’ to mark all of the tagged bookmarks.)
- ‘T e’ (‘C-x p t e’) lets you edit a bookmark’s tags.
- ‘T l’ (‘C-x p t l’) lists all tags currently known to Emacs (across all bookmarks).
- Keys that add/remove tags:
- `T +’ (`C-x p t + b’) adds some tags to a bookmark.
- ‘T -’ (‘C-x p t - b’) removes some tags from a bookmark.
- ‘T 0’ (‘C-x p t 0’) removes all tags from a bookmark.
- ‘T d’ (‘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 ‘Java’ and ‘ide’?
- ‘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 ‘blue’ and ‘moon’ first?
- ‘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 `s >’.
How would you query-replace the set of files that are tagged with any of the tags ‘alpha’, ‘beta’, and ‘gamma’, but are not tagged ‘blue’ or ‘moon’?
- ‘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 ‘blue’ or ‘moon’.
- ‘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 ‘bmkp-bmenu-dired-marked’ (`M-d >’) weds Bookmark+’s set-defining and set-manipulating features (tagging, marking, filtering etc.) to Dired’s file-manipulating features.
`M-d >’ opens a Dired buffer that is specialized for just the files and directories whose bookmarks are marked in the bookmark list. (Other marked bookmarks are ignored by the command.) The files and directories can be located anywhere; they need not be in the same directory. They are listed in Dired using absolute file names.
(In Emacs versions prior to release 23.2, only local files and directories can be handled, due to Emacs bug #5478. In such versions, remote-file bookmarks are ignored by `M-d >’.)
This Bookmark+ feature makes sets of files and directories immediately amenable to all of the operations provided by Dired.
It is particularly useful in conjunction with tags. Use bookmark tags and marks to define a possibly complex set of file and directory bookmarks. Then hit `M-d >’ to list them in a Dired buffer. Then use any Dired commands you want to act on any of them.
For example, to compress bookmarked files that are tagged with both ‘blue’ and ‘moon’:
- Mark them using ‘T m * blue RET moon RET RET’.
- Open Dired for them using `M-d >’.
- Mark them in Dired, then compress them using ‘Z’.
Since tags are persistent, Bookmark+ gives you a good way to define an arbitrary set of files as a project and then open them in Dired at any time to operate on them.
If you use Dired+ (library dired+.el), then a similar feature is available for the marked files and directories: You can use ‘C-M-*’ in Dired to open a separate Dired buffer for them only. You can of course then bookmark that resulting Dired buffer, if you like.
If you use Icicles, then whenever you use a command that reads a file (or directory) name, you can use `M-|’ during file-name completion to open Dired on the currently matching set of file names. That is, this is the same kind of special Dired buffer that is provided for file and directory bookmarks by `M-d >’ in the bookmark list.
Bookmark+ enhances marking and unmarking of bookmarks in the bookmark list in several ways. In general, these enhancements are similar to features offered by Dired and Dired X. You can use:
- `% 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.
- ‘M-DEL’ (or ‘U’) to unmark all bookmarks, or all that are marked `>’, or all that are flagged ‘D’ for deletion.
- ‘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.
- ‘F M’, ‘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.
There are three ways to show only certain bookmarks.
- Filter by bookmark type.
- Filter bookmarks incrementally and temporarily, using pattern matching.
- Filter out the marked or unmarked bookmarks.
The commands that show only bookmarks of a particular type are bound to keys that end in ‘S’ (for “show”). For example, ‘I S’ shows only Info bookmarks, and ‘X S’ shows only temporary bookmarks.
The type filter is reflected in the bookmark-list display title. It says ‘All Bookmarks’ if no type filter is used. Otherwise it tells you what kind of bookmarks are listed: ‘Autonamed Bookmarks’, ‘File and Directory Bookmarks’, and so on.
Note: It is only filtering by bookmark type that is remembered when you save a bookmark-list display state or you create a bookmark-list bookmark. See State-Restoring Commands and Bookmarks.
These commands show only bookmarks that in some way match a pattern (regexp) that you type. The bookmarks are filtered incrementally as you type the pattern. Hit any non-inserting key, such as ‘RET’, to finish defining the pattern.
The commands for this are bound to keys that start with ‘P’ (for “pattern”). For example, ‘P B’ shows only bookmarks whose names match the regexp, ‘P F’ shows those whose file names match, ‘P A’ shows those whose annotations match, and ‘P T’ shows those that have one or more tags that match. (See BookmarkTags, above, for information about tags.)
Just as in Dired, you can use `% m’ to mark the bookmarks that match a regexp. Then use `>’ to show only the marked bookmarks. See MarkingAndUnmarkingBookmarks, above.
This method has the advantage that you can show the complement: the bookmarks that do not match the regexp, by using `<’ instead of `>’. It also has the advantage that matching checks the combination of bookmark name and file name (use ‘M-t’ to toggle showing file names).
These are the keys for hiding or showing bookmarks:
- `.’ – 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.
- ‘X S’ – Show only temporary 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.
For example:
- ‘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.
In sections MarkingAndUnmarkingBookmarks and FilteringBookmarks you learned how to hide and show bookmarks in the bookmark list. This section is about a different kind of hiding, called omitting.
Omitted bookmarks are not shown in the bookmark list, no matter what filtering is used. The only way to show omitted bookmarks is to show all of them and only them, using ‘- S’, which is bound to command ‘bmkp-bmenu-show-only-omitted’.
Omitted bookmarks are still available even if they are not shown, and you can still jump to them (e.g. using ‘C-x r b’). You just don’t see them in the bookmark list. And that’s the reason for this feature: to hide those bookmarks that you don’t care to see.
One use for this feature is to hide the component bookmarks that make up a sequence bookmark (see FunctionSequenceVarlistBookmarks). The default behavior when you create a sequence bookmark is in fact to omit its component bookmarks from the displayed list.
You can omit any bookmarks by marking them and then using `- >’ (‘bmkp-bmenu-omit/unomit-marked’). If you are looking at the omitted bookmarks (after using ‘- S’), then `- >’ un
-omits the bookmarks marked there. Think of two complementary spaces: the normal bookmark list and the omitted bookmark list. When you use `- >’, the marked bookmarks that are currently shown are moved to the opposite space.
You can un-omit all of the omitted bookmarks at once, using ‘- U’ (‘bmkp-unomit-all’). You can also call this command from outside the bookmark-list display.
Omitted bookmarks that are marked are generally not included when you use a command that acts on the marked bookmarks. However, if you use a negative prefix argument with the command then they are.
For some commands this is relaxed so that any prefix arg has this effect. For other commands a non-negative prefix arg has a different effect. In some cases, a non-negative prefix arg has one effect and a non-positive prefix arg has the effect of including omitted marked bookmarks, so that a zero prefix arg has both effects. For any given command, consult the doc string for full information.
Filtering hides certain kinds of bookmarks. Sometimes, you want to see bookmarks of various kinds, but you want them to be grouped or sorted in different ways, for easy recognition, comparison, and access.
Bookmarks shown in the bookmark list are sorted using the current value of option ‘bmkp-sort-comparer’. (If that is ‘nil’, they are unsorted, which means they appear in reverse chronological order of their creation.)
You can use ‘s s’… (repeat hitting the ‘s’ key) to cycle among the various sort orders possible, updating the display accordingly. By default, you cycle among all available sort orders, but you can shorten the cycling list by customizing option ‘bmkp-sort-orders-for-cycling-alist’.
You can also change directly to one of the main sort orders (without cycling) using `s >’, ‘s n’, ‘s f n’, etc. There are many such predefined sort orders bound to keys with the prefix ‘s’ — use ‘C-h m’ or `?’ for more info.
- `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 (‘s k’).
Be aware that ‘s C-r’ can be a bit unintuitive. If it does not do what you expect or want, or if it confuses you, then don’t use it ;-). (‘s C-r’ has no noticeable effect on simple sorting.)]
Remember that you can combine sorting with filtering different sets of bookmarks – bookmarks of different kinds (e.g. Info) or bookmarks that are marked or unmarked.
Finally, you can easily define your own sorting commands and sort orders. See macro ‘bmkp-define-sort-command’ and the documentation for option ‘bmkp-sort-comparer’. (Bookmark+ uses option ‘bmkp-sort-comparer’; it ignores vanilla Emacs option ‘bookmark-sort-flag’.)
Of particular note is that you can interactively define commands that sort by a given list of tags — you use keys ‘T s’ (command ‘bmkp-define-tags-sort-command’) to do that. You are prompted for the tags to sort by. Bookmarks are sorted first according to whether they are tagged with the first tag, then the second tag, and so on. Otherwise, sorting is by bookmark name.
The tags you specify are used, in order, in the name of the new command. For example, if you enter tags ‘alpha’, ‘beta’, and ‘gamma’, in that order, then the sorting command created is ‘bmkp-bmenu-sort-alpha-beta-gamma’. The new command is saved in your bookmark commands file (‘bmkp-bmenu-commands-file’).
Note that because you can add a new tag to all bookmarks that have some given set of tags, you can use that single (new) tag to represent the entire tag set. Sorting by that tag is then the same as sorting by the tag set. You can of course use overlapping sets in the composite sort command. You can, for example, sort first according to tag ‘tag1’, which represents the set of tags ‘alpha’, ‘beta’, ‘gamma’, ‘delta’, and then sort according to tag ‘tag2’, which represents the set of tags ‘beta’, ‘delta’.
See also ApplesAndOranges for more about the sorting used in Bookmark+. See also bookmark sorting in Icicles – the same technique is used in Icicles for sorting bookmarks as completion candidates.
A bookmark typically records a position or a region in a file or buffer. Sometimes you are interested in accessing or examining only the bookmarks for particular files or buffers. For example, you might want to navigate among the bookmarks for the current buffer. Or you might want to search the regions recorded in the bookmarks for a particular file.
For a bookmark, the recorded file and buffer name differ in that the file name is absolute. Bookmarks for buffer `foo.el’ include all files named `foo.el’, whereas bookmarks for file `/project1/lisp/foo.el’ include only the files in that one directory.
Another important difference is that when multiple buffers visit different files that have the same relative file name (i.e., in different directories), Emacs makes the buffer names unique by appending `<N>’ as needed, where ‘N’ is 2, 3,… When you create a bookmark, the current buffer name is recorded as the bookmark’s buffer. If the current buffer is not visiting a file, then the bookmark created is a non-file bookmark. In that case, to use the bookmark later you must have a buffer of the same name (e.g. `foo.el<2>’).
Bookmark+ provides commands to handle these different use cases: specific files and specific buffers. The keys bound to these commands use ‘f’ for file and ‘b’ for buffer. In the bookmark-list display, the following keys affect the bookmarks for a particular file or buffer whose name you provide (with completion).
- `= 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 ‘bmkp-use-region’ is ‘t’, not ‘cycling-too’, which means that when you cycle to a bookmark its recorded region (if any) is not activated. This is probably what you want most of the time. Cycling is a repetitive action, and if you cycle to a bookmark with no recorded region then an already active region is just extended. Customize the value to ‘cycling-too’ if you prefer that behavior.
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 ‘*Bookmark List*’.
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. ‘dired’).
For ‘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:
- If you cycle using a current-file/buffer cycling key such as ‘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.
- Otherwise, a snapshot is taken of the the bookmarks currently in the global bookmark list (the value of variable ‘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 `*Bookmark List*’ state at any given time necessarily reflects the navlist bookmarks. The two are separate. You can, however, open the ‘*Bookmark List*’ so that it reflects the bookmarks currently in the navigation list, using ‘C-x p N’ (‘bmkp-navlist-bmenu-list’).
So you choose a navigation list. How do you then cycle among its bookmarks?
Commands ‘bmkp-next-bookmark’ and ‘bmkp-previous-bookmark’ cycle to the next and previous bookmark in the navigation list (with wraparound).
You can bind these to any keys you like, but it’s obviously better to choose keys that are easily repeatable (e.g. by holding them pressed). Some people who are used to using MSVisualStudio might want to use ‘f2’ and ‘S-f2’ to cycle forward and backward.
Bookmark+ does not define such key bindings, but you can. What it does is define repeatable keys on the ‘bookmark-map’ keymap, which 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:
Forward: ‘C-x p f’, ‘C-x p C-f’, ‘C-x p right’
Backward: ‘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:
Forward: ‘C-x p next’ (PageDown key)
Backward: ‘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 `*Bookmark List*’ then the characteristics of that bookmark display are respected for navigation. Only the bookmarks visible in ‘*Bookmark List*’ are included, and the ‘*Bookmark List*’ sort order is used for navigation.
So you can not only choose any set of bookmarks for cycling at any given time, you can also cycle among them in an order you choose. For example, if in the bookmark list display (‘C-x 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-next-autonamed-bookmark-repeat’, ‘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 ‘bmkp-next-bookmark-this-file/ buffer-repeat’ and ‘bmkp-previous-bookmark-this-file/buffer-repeat’:
Next: ‘C-x p n’, ‘C-x p C-n’, ‘C-x p down’
Previous: ‘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. ‘f2’, ‘S-f2’). If you do not need to use a prefix key, then bind commands ‘bmkp-next-bookmark-this-file/buffer’ and ‘bmkp-previous-bookmark-this-file/buffer’ (no -repeat).
You can also cycle among just the highlighted bookmarks in the current file or buffer – see Using Highlighted Bookmarks.
Cycling among bookmarks for the current file or buffer (whether all bookmarks or only the highlighted ones) is dynamic: the current set of bookmarks is cycled, not a static snapshot taken at some point in past. The navlist is automatically updated to the current dynamic set each time you cycle. This is different from the usual cycling of the navlist, where it is taken as a static snapshot – see The Bookmark Navigation List.
By default, you cycle among the bookmarks for the current file or buffer in order of their buffer positions, top to bottom. If you want a different order, you can customize option ‘bmkp-this-file/buffer-cycle-sort-comparer’.
Alternatively, you can use `C-x p ,’ to display the `*Bookmark 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 `000058356 foo.el’.
(You can customize the format of autonamed bookmarks using options ‘bmkp-autoname-bookmark-function’ and ‘bmkp-autoname-format’.)
When you jump to any bookmark, the actual destination can differ from the recorded position, because the buffer text might have changed. In that case, the position you jump to has been automatically relocated using the recorded bookmark context (some buffer text surrounding the original position).
If option ‘bmkp-save-new-location-flag’ is non-‘nil’ then, after jumping, the recorded position of the bookmark is automatically updated to reflect the new location jumped to. This is true for any bookmark.
In the case of an autonamed bookmark, the bookmark name 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
- ‘bmkp-occur-create-autonamed-bookmarks’ (‘C-c b’ in ‘*Occur*’) – - At ‘occur’ and ‘multi-occur’ hits
Autonamed bookmarks are normal bookmarks. In particular, they are persisted. If you do not care to persist them, you can ensure that they are automatically deleted by adding ‘bmkp-delete-autonamed-this-buffer-no-confirm’ to ‘kill-buffer-hook’ and ‘bmkp-delete-autonamed-no-confirm’ to ‘kill-emacs-hook’:
(add-hook ‘kill-buffer-hook ‘bmkp-delete-autonamed-this-buffer-no-confirm) (add-hook ‘kill-emacs-hook ‘bmkp-delete-autonamed-no-confirm)
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:
- Use ‘C-x p 0’ (‘bmkp-empty-file’) to create a new, empty bookmark file.
- Use ‘C-x p L’ (‘bmkp-switch-bookmark-file-create’) to switch to using that new, empty bookmark file.
- Use ‘M-x bmkp-toggle-saving-bookmark-file’ to turn off auto-saving bookmarks to disk.
This is essentially what the minor-mode toggle command ‘bmkp-temporary-bookmarking-mode’ does. When in this minor mode, bookmarks that you create are stored on the new bookmark list, which is not automatically saved to disk. If you do not explicitly save it yourself then the bookmarks are lost when your Emacs session ends – they are only temporary.
This command is bound to ‘M-L’ in the bookmark-list display buffer (‘*Bookmark List*’). The suffix ‘L’ indicates that this has to do with l
oading a bookmark file. See Using Multiple Bookmark Files.
In the bookmark-list display, temporary bookmarking mode is indicated in the mode line by ‘TEMPORARY Bookmarking’ in place of ‘Bookmarks’ as the mode name.
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).
- At the individual-bookmark level, commands ‘bmkp-make-bookmark-temporary’ and ‘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 (‘X S’).
- At the bookmark-type level, you can customize user option ‘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-bookmark-p’ and ‘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.
- Finally, you can toggle whether all bookmarks become temporary whenever they are created or updated, using command ‘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.
Mode ‘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-auto-idle-bookmark-mode-lighter’.
Command ‘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.
Option ‘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.)
Option ‘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-bookmark-p’ or ‘bmkp-autonamed-this-buffer-bookmark-p’ (it includes both of these by default). Remember that you can toggle whether a given bookmark is temporary or savable, using ‘M-X’ in the bookmark-list display (buffer ‘*Bookmark List*’).
If you want the bookmarks to be automatically highlighted, then customize option ‘bmkp-auto-light-when-set’ to highlight bookmarks of the appropriate kind. For example, to highlight autonamed bookmarks set it to ‘autonamed-bookmark’.
NOTE: If you use Emacs 20, then by default ‘bmkp-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 ‘define-globalized-minor-mode’.
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.
- ‘bmkp-light-autonamed’ (face)
- ‘bmkp-light-non-autonamed’ (face)
- ‘bmkp-light-style-autonamed’ (option)
- ‘bmkp-light-style-non-autonamed’ (option)
- ‘bmkp-light-left-fringe-bitmap’ (option)
- ‘bmkp-light-right-fringe-bitmap’ (option)
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 ‘*Bookmark List*’):
- `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’ and ‘this-bookmark-name’, whose values are the bookmark to be highlighted and its name, respectively.
So, for example, if you wanted to be prompted each time before highlighting a certain bookmark you might set its highlighting condition to a sexp such as this:
(or (y-or-n-p (format “Highlight `%s’ ” this-bookmark-name)) :no-light)
If you hit ‘n’ at the prompt then `:no-light’ is returned and the bookmark is not highlighted.
In the bookmark-list display, a pink-background, one-character highlight is used next to each bookmark that has a highlight override wrt the default. You can see what that override setting is by using ‘C-u C-h RET’ – look for the ‘lighting’ entry in the bookmark definition.
You can highlight or unhighlight a bookmark or a set of bookmarks on demand.
In the bookmark list (buffer ‘*Bookmark List*’):
- ‘H H’, ‘H U’ – Highlight, unhighlight this line’s bookmark
- `H > H’, `H > U’ – Highlight, unhighlight the marked bookmarks
Globally:
- ‘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:
- With plain ‘C-u’: all bookmarks
- With ‘C-u C-u’: navigation-list bookmarks
- Otherwise, bookmarks in current buffer: o No prefix arg: all bookmarks o Prefix arg > 0: autonamed bookmarks o Prefix arg < 0: non-autonamed 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:
- Negative arg: prompted for style
- Non-negative arg: prompted for face
- Plain ‘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:
- ‘bmkp-auto-light-when-set’
- ‘bmkp-auto-light-when-jump’
You can choose any of these values for either option:
- ‘Autonamed bookmark’
- ‘Non-autonamed bookmark’
- ‘Any bookmark’
- ‘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 (‘*Bookmark List*’). ‘H S’ shows only the bookmarks that are currently highlighted, and ‘H M’ marks them. You can then perform any of the available bookmark-list operations on them.
Globally, you can use these keys:
- `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.
You can use command ‘bmkp-insert-bookmark-link’ to create links in any Emacs text that jump to particular bookmarks when you follow them (by hitting ‘RET’ or clicking ‘mouse-2’). If you hit `?’ or double-click ‘mouse-1’ on such a bookmark link then the bookmark is described, showing the same information as `C-x p ?’ (‘bmkp-describe-bookmark’).
You are prompted for the bookmark to link. If the region is active and nonempty then the link is put on its text. Otherwise, you are prompted for the link text, which is inserted. The default link text is the bookmark name in this case.
The bookmark linked can be of any type.
This simple feature lets you easily create “launching pads” for different sets of bookmarks: buffers or files that consist of bookmark links and any other text you like. This gives you yet another way to organize bookmarks (and so also the files, directories, etc. that they target).
If you also use library font-lock+.el then the links appear with face ‘link’, even in a font-locked buffer. (Library font-lock+.el just provides this feature of allowing non-font-lock highlighting in a font-locked buffer. See http://lists.gnu.org/archive/html/emacs-devel/2014-08/msg00540.html.)
The links you create this way are not persistent, but you can of course re-create them using Lisp.
You can also easily define OrgMode links that jump to bookmarks. These links are persistent. Again, the bookmark linked can be of any type. 可以定義 Org Mode 下的連結去跳轉到書籤。
You can use the standard Org command ‘org-store-link’ (‘C-c l’) in buffer ‘*Bookmark List*’ to store a link to the bookmark at point. 在書籤列表中按下 ‘C-c l’以存下所在位置的書籤，成為一個連結(的候選人)。
Outside buffer ‘*Bookmark List*’ you can use command ‘bmkp-store-org-link’ to store a link to any bookmark. You are prompted for the bookmark name. You can even enter the name of a bookmark that does not yet exist.
If you use a numeric prefix arg with either command then the bookmark link stored will be for jumping to the bookmark in the same window. Without a numeric prefix arg, the link will use another window. (Org mode defines other behaviors for non-numeric prefix args, such as ‘C-u C-u’.)
As usual, to insert a bookmark link, you use command ‘org-insert-link’. Enter the name of the target bookmark at the prompt. In Org mode you can use the usual Org key bindings to follow the link. In any mode you can use standard Org command ‘org-open-at-point-global’ (not bound to a key by default). 在 Org 檔案中可以按下 ‘C-c C-l’ 以插入剛才所存下的連結。將出現連結(的候選人)清單以供您挑選。
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:
- No prefix arg: Prompt for the bookmark name. The candidates are bookmarks in the current buffer (or all bookmarks if there are none in the current buffer).
- (Non-negative) numeric prefix arg: No prompt. Use the buffer name plus the text of the region (if active) or the current line as the bookmark name. Quickest way to set a bookmark.
- Plain ‘C-u’: 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 ‘*Bookmark List*’:
- Candidates are highlighted in the ‘*Completions*’ window according to their bookmark type.
- Candidates are Icicles multi-completions with up to three parts: (a) the bookmark name, the bookmark file or buffer name, and (c) any
tags.
You can match any or all of the parts. For example, you can match bookmarks that have tags by typing this regexp: `C-M-j . * C-M-j S-TAB’. Each ‘C-M-j’ inserts `^G\n’, which is `icicle-list-join-string’, the string used to join the parts. This regexp says, “match the completion candidates that have all three parts (two join strings), hence some tags. You can turn off the use of multi-completion candidates for subsequent commands, so only bookmark names are used, by hitting ‘M-m’ in the minibuffer. You can think of this as similar to using ‘M-t’ in ‘*Bookmark List*’ to toggle showing file names. You can make not showing files and tags the default behavior by customizing `icicle-show-multi-completion-flag’.
- You can sort completion candidates using the Bookmark+ sort orders. Use `C-,’ to cycle among sort orders.
- You can use Icicles candidate-help keys (‘C-M-RET’, ‘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 ‘*Completions*’.
- You can use Icicles candidate-action keys (‘C-RET’, ‘C-mouse-2’, ‘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.
- You can use ‘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.
- You can define Icicles sets of bookmarks, persistent or not, and act on their members in various ways.
During file-name completion, you can do any of the following on the fly:
- Jump to one or more file bookmarks, using ‘C-x m’.
- Create one or more autofile bookmarks, using ‘C-x a a’.
- Add tags to one or more files (autofile bookmarks), using `C-x a +’.
- Remove tags from one or more files (autofile bookmarks), using ‘C-x a -’.
There are 25 Icicles commands for searching bookmark destinations! The most general is ‘icicle-search-bookmark’. Others let you search specific kinds of bookmarks, or bookmarks having various combinations of tags.
During Icicles search (of anything, not just a bookmark destination), you can save sets of completion candidates, which means sets of search hits, as bookmarks. And Icicles lets you use set operations (complement, union, intersection, difference etc.) on the current set of search hits.
When you “jump” to an Icicles search-hits bookmark, its recorded search hits are restored to Icicles search as completion candidates, either replacing the current candidates or adding to them.
You can thus save and later return to different sets of search results using different bookmarks. You can “jump” to an Icicles search-hits bookmark during any Icicles search, whether you search a file, a buffer, multiple files, or multiple buffers.
See Also: Icicles - Bookmark Enhancements.
Bookmark+ is generally compatible with GnuEmacs versions 20 and later. You can use bookmarks with Bookmark+ regardless of whether they were created using Bookmark+ or vanilla Emacs (i.e., library bookmark.el).
But for best results, if you have bookmarks that you created using Bookmark+ then use Bookmark+, not vanilla Emacs, to access them. This section provides details.
Set user option ‘bmkp-propertize-bookmark-names-flag’, depending on your usage scenario (the default is ‘t’ for Emacs 21 and later, ‘nil’ for Emacs 20):
- Set it to ‘nil’ if you will often be going back and forth between using Bookmark+ and using vanilla Emacs. (Do this also if you use Emacs 20.)
- Set it to non-‘nil’ if you instead always use only Bookmark+ (with Emacs 21 or later), or you use vanilla Emacs only to jump to bookmarks but never to update or create bookmarks.
#1 is VERY IMPORTANT
. You can lose data if you do not respect it.
The reason for rule #1 is this: When the option is non-‘nil’ Bookmark+ writes bookmarks to your bookmark file in a format that can be read and used by vanilla Emacs (21 and later) but which vanilla Emacs then saves as unreadable. If the option value is ‘nil’ there is no such problem.
#2 is not a requirement. It is just a good idea, to be able to take better advantage of Bookmark+. If you set the option to ‘nil’ then you cannot use multiple bookmarks that have the same name. Vanilla Emacs does not make good use of such critters, but Bookmark+ does. Having multiple bookmarks with the same name is particularly useful for autofiles. It means you can have different autofiles in different directories but with the same name. See Autofile Bookmarks.
Here is what happens when ‘bmkp-propertize-bookmark-names-flag’ is non-nil:
Besides its name, which is what you see and use most of the time, a bookmark contains other information such as the target location, textual context hints, and last access time. Non-‘nil’ ‘bmkp-propertize-bookmark-names-flag’ has no effect on vanilla Emacs, but it causes Bookmark+ to put the full bookmark information on the bookmark name as a text property.
The name thus encapsulates all of the information contained in the full bookmark of which it is part. Knowing the name is then enough to know everything about the bookmark. Part of the bookmark (its name) refers to the whole of it. In Lisp this self-reference is implemented using circular structures.
When Bookmark+ saves such circular structures to your bookmark file, if the option is non-‘nil’ then it takes care to do so in such a way that they can be read in again when your bookmark file is loaded. In Lisp terms, it binds ‘print-circle’ to non-‘nil’ when it writes your bookmarks. If the option value is ‘nil’ then the circularity (self-reference) is removed before your bookmarks are saved. Either way, the file is readable.
Vanilla Emacs (21 and later) has no problem reading your bookmark file if it contains such circular structures. But if you then use it to save the file again, the Lisp code it writes has invalid Lisp ‘read’ syntax (because it does not remove the circularity but it also does not bind ‘print-circle’ to non-‘nil’).
If that happens, the result is a bookmark file that is unreadable
. It cannot be loaded into either vanilla Emacs or Bookmark+. If you do not have an uncorrupted backup version of the file to revert to, then you will need to edit it by hand to clean it up.
So do not let that happen to you! For best results use only Bookmark+ to access bookmarks created using Bookmark+.
If you must use vanilla Emacs with your bookmarks, then make sure they are not saved by Bookmark+ with the option non-‘nil’: Using Bookmark+, set the option to ‘nil’ and then save the file.
That is:
- ‘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’ (‘C-c C-C’, aka ‘C-c C-S-c’). See State-Restoring Commands and Bookmarks.
Here are screenshots of the various Bookmark+ menus. Using the menus is a good way to learn some of the features (and their key bindings).
Menu-Bar Edit Menu
Bookmark+ adds two items to the menu bar Edit menu:
- Save the active region text as a bookmark.
- “Jump to” the bookmark to copy the text to the kill ring, so you can then yank it anywhere.
Bookmark
`mouse-3’ Popup Menu in `*Bookmark List*’
It has actions for the individual bookmark you point to when you pop it up.
Bookmark
Bookmark+ Menu-Bar Menu in `*Bookmark List*’
The same menu is available on ‘C-mouse-3’.
Bookmark+ Bookmark
It has submenus Icicles (if you use Icicles), Jump To, Delete, Mark, Omit, Show, Sort, Search, Tags, Highlight, Toggle, Bookmark File, and Define Command.
The Jump To menu has submenus Icicles (if you use Icicles) and With Tags. The Icicles submenu has its own submenu With Tags.
The Mark has submenu Bookmarks of Type.
The Show Menu has submenu Only Bookmarks of Type.
Icicles submenu of Bookmark+ menu-bar menu Bookmark
Jump To submenu of Bookmark+ menu-bar menu Bookmark
Icicles submenu of Jump To submenu of Bookmark+ menu-bar menu Bookmark
With Tags submenu of Icicles submenu of Jump To submenu of Bookmark+ menu-bar menu (Emacs 21+ only) Bookmark
With Tags submenu of Jump To submenu of Bookmark+ menu-bar menu (Emacs 21+ only) Bookmark
Delete submenu of Bookmark+ menu-bar menu Bookmark
Mark submenu of Bookmark+ menu-bar menu Bookmark
Bookmarks of Type submenu of Mark submenu of Bookmark+ menu-bar menu Bookmark
Omit submenu of Bookmark+ menu-bar menu Bookmark
Show submenu of Bookmark+ menu-bar menu Bookmark
Only Bookmarks of Type submenu of Show submenu of Bookmark+ menu-bar menu Bookmark
Sort submenu of Bookmark+ menu-bar menu Bookmark Search submenu of Bookmark+ menu-bar menu Bookmark Tags submenu of Bookmark+ menu-bar menu Bookmark Highlight submenu of Bookmark+ menu-bar menu Bookmark
Toggle submenu of Bookmark+ menu-bar menu Bookmark Bookmark File submenu of Bookmark+ menu-bar menu Bookmark Define Command submenu of Bookmark+ menu-bar menu Bookmark
Vanilla Bookmarks Menu
The vanilla Bookmarks menu provided by Emacs is typically a submenu of the Edit menu bar menu. Bookmark+ modifies it by adding several Bookmark+ items and submenus.
Bookmarks Bookmark
Jump To submenu of Bookmarks menu-bar menu Same as Bookmark+ submenu Jump To Tags submenu of Bookmarks menu-bar menu Bookmark Toggle submenu of Bookmarks menu-bar menu Same as Bookmark+ submenu Toggle New/Update submenu of Bookmarks menu-bar menu Bookmark Delete submenu of Bookmarks menu-bar menu Bookmark Highlight submenu of Bookmarks menu-bar menu Bookmark
Vanilla File Menu
Bookmark+ adds submenu ‘Find File or Autofile’ to the vanilla File menu provided by Emacs.
Bookmark
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.
Bookmark Bookmark Bookmark Bookmark Bookmark Bookmark Bookmark
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.
Bookmark
Major mode for editing a list of bookmarks. Each line in `*Bookmark List*’ represents an Emacs bookmark.
Bookmark file: ~/Dropbox/.emacs.d/bookmark Sorted: Filtering: none Marked: 0 Omitted: 0 Autosave bookmarks: yes Autosave list display: yes
> marked D flagged for deletion (`x’ to delete all such) t tagged (`C-h C-RET’ to see) a annotated (`C-h C-RET’ to see)
- modified (not saved)
X temporary (will not be saved)
Image file Gnus Info node Man page URL Local file with no region Local file with a region No such local file Buffer No such buffer now Remote file/directory or Dired buffer (could have wildcards) Remote accessed by `su’ or `sudo’ Local directory or Dired buffer (could have wildcards) Bookmark with property `file-handler’ Bookmark List Bookmark file Snippet Desktop Sequence Variable list Function Bookmarks you cannot jump to from `*Bookmark List*’ Possibly invalid bookmark
Keys without prefix `C-x’ are available only here (`*Bookmark List*’). Keys with prefix `C-x’ are available everywhere.
Remember that you can see all bindings for a prefix key by hitting it, then `C-h’. E.g., `s C-h’ to see keys with prefix `s’ (sorting).
M-t - Toggle showing filenames next to bookmarks C-h RET - Show information about bookmark (`C-u’: internal form) <C-down> - Show the info, then move to next bookmark <C-up> - Show the info, then move to previous bookmark C-h > - Show info about the marked bookmarks (`C-u’: internal form) C-S-l - Show location of bookmark (in minibuffer) a - Show bookmark’s annotation (`C-u’: edit it) M-a - Show the annotations of all annotated bookmarks
M-x bmkp-list-defuns-in-commands-file
- List the commands defined in `bmkp-bmenu-commands-file’
C-M-~ - Toggle autosaving bookmark-list display state M-x bmkp-save-menu-list-state - Save bookmark-list display state
g - Refresh display to current bookmark list (`C-u’: from file) . - Show all bookmarks M-x bmkp-toggle-bookmark-set-refreshes
- Toggle whether `bookmark-set’ refreshes the bookmark list
h - Show this help q - Quit (`*Bookmark List*’)
M-~ - Toggle autosaving to the current bookmark file S - Save bookmarks now (`C-u’: Save As… - prompt for file)
C-u g - Revert to bookmarks in the bookmark file (overwrite load) L - Switch to a different bookmark file (overwrite load) C-u L - Switch back to the previous bookmark file (overwrite load) l - Add bookmarks from a different bookmark file (extra load) M-l - Load marked bookmark-file bookmarks (extra load)
Y > - - Move the marked bookmarks to a bookmark file Y > + - Copy the marked bookmarks to a bookmark file Y > 0 - Copy the marked bookmarks to a new bookmark file C-u Y > 0 - Same, plus create bookmark-file bookmark for it C-x p 0 - Empty a bookmark file or create a new, empty bookmark file
Here:
M-d > - Open Dired for the marked file and directory bookmarks M-x bmkp-bmenu-make-sequence-from-marked
- Create a sequence bookmark from the marked bookmarks
M-L - Toggle temporary-only bookmarking (new, empty bookmark file)
Anywhere:
C-x p x - Toggle making bookmarks temporary when setting them C-x p y - Create a bookmark to a bookmark file (`j y’ to load it) C-x p <delete> - Delete some bookmarks at point or all in buffer C-x p c F - Create a function bookmark C-x p : - Set the navlist to the bookmarks of a type you choose C-x p B - Set the navlist to the bookmarks of a bookmark-list bookmark C-x p N - Open `*Bookmark List*’ for bookmarks in navlist C-x p , - Open `*Bookmark List*’ for bookmarks in current file/buffer
C-x p RET - Set/delete an autonamed bookmark here C-x p c a - Set and autoname a bookmark for a file C-x p c f - Set a bookmark for a file C-x p c u - Set a bookmark for a URL C-x p m - Set a bookmark here C-x p K - Set a bookmark for the current desktop C-x p y - Set a bookmark for a bookmark file C-x p M-w - Save the region text as a snippet bookmark
RET - This bookmark in the same window o - This bookmark in another window C-o - This bookmark in other window, without selecting it 1 - This bookmark in a full-frame window 2 - This bookmark and last-visited bookmark
j > - Bookmarks marked `>’, in other windows
Prefix `j’ uses another window; prefix `J’ reuses this window:
C-x 4 j j - Bookmark by name j N - Bookmark in the navigation list j h - Highlighted bookmark
j : - Bookmark by type j # - Autonamed bookmark j , # - Autonamed bookmark in this buffer j x - Temporary bookmark
j a - Autofile bookmark j d - Dired bookmark j f - File or directory bookmark j . d - Dired bookmark for this dir j . f - Bookmark for a file or subdir in this dir j l - Local-file bookmark j n - Remote-file bookmark j b - Non-file (buffer) bookmark
j K - Desktop bookmark j B - Bookmark-list bookmark j y - Bookmark-file bookmark
j r - Region bookmark (restores region) j M-w - Snippet bookmark (copy to `kill-ring’) j M-i - Image-file bookmark j i - Info bookmark j m - `man’-page bookmark j g - Gnus bookmark j u - URL bookmark j v - Variable-list bookmark
j t + - Bookmark having some tags you specify j t * - Bookmark having each tag you specify j t % + - Bookmark having a tag that matches a regexp j t % * - Bookmark having all its tags match a regexp j t f + - File bookmark having some tags you specify j t f * - File bookmark having each tag you specify j t f % + - File bookmark having a tag that matches a regexp j t f % * - File bookmark having all its tags match a regexp j t . + - File in this dir having some tags you specify j t . * - File in this dir having each tag you specify j t . % + - File in this dir having a tag that matches a regexp j t . % * - File in this dir having all its tags match a regexp
C-x p RET - Create/delete autonamed bookmark at point C-u C-x p RET - Delete all autonamed bookmarks in current buffer j # - Jump to an autonamed bookmark j , # - Jump to an autonamed bookmark in a given buffer
C-x p n n … - Next bookmark in buffer (C-x p C-n, C-x p down) C-x p p p … - Prev bookmark in buffer (C-x p C-p, C-x p up) C-x p f f … - Next bookmark in navlist (C-x p C-f, C-x p right) C-x p b b … - Prev bookmark in navlist (C-x p C-b, C-x p left) C-x p next … - MS Windows `Open’ next bookmark in navlist C-x p prior … - MS Windows `Open’ previous bookmark in navlist C-x C-down … - Next highlighted bookmark in buffer C-x C-up … - Prev highlighted bookmark in buffer
M-s a C-s - Isearch the marked bookmarks (`C-u’: all) M-s a C-M-s - Regexp-isearch the marked bookmarks (`C-u’: all) M-s a M-s - Regexp-search the marked file bookmarks (`C-u’: all) M-q - Query-replace the marked file bookmarks
(Mark means `>’. Flag means `D’. See also `Tags’, below.)
d - Flag bookmark `D’ for deletion, then move down C-d - Flag bookmark `D’ for deletion, then move up
m - Mark bookmark u - Unmark bookmark (`C-u’: move up one line) DEL - Unmark previous bookmark (move up, then unmark)
M-m - Mark all bookmarks % m - Mark all bookmarks whose names match a regexp U - Unmark all bookmarks (`C-u’: interactive query) t - Toggle marks: unmark the marked and mark the unmarked
A M - Mark autofile bookmarks
X M - Mark temporary bookmarks M-x bmkp-bmenu-mark-lighted-bookmarks - Mark highlighted bookmarks (requires `bookmark+-lit.el)
B M - Mark non-file (i.e. buffer) bookmarks M-d M-m - Mark Dired bookmarks F M - Mark file & directory bookmarks (`C-u’: local only) G M - Mark Gnus bookmarks I M - Mark Info bookmarks i M - Mark Icicles search-hits bookmarks M-I M-M - Mark image-file bookmarks K M - Mark desktop bookmarks M M - Mark `man’ page bookmarks (that’s `M’ twice, not Meta-M) O M - Mark orphaned local file/dir bookmarks (`C-u’: remote also) R M - Mark region bookmarks Q M - Mark function bookmarks M-u M-m - Mark URL bookmarks V M - Mark variable-list bookmarks W M - Mark W3M (URL) bookmarks w M - Mark snippet bookmarks Y M - Mark bookmark-file bookmarks Z M - Mark bookmark-list bookmarks
(See also `Tags’, next.)
r - Rename or relocate bookmark M-r - Relocate bookmark M-R - Relocate marked bookmarks T e - Edit bookmark’s tags C-u a - Edit bookmark’s annotation e - Edit internal Lisp record for bookmark E - Edit internal Lisp records of marked bookmarks (`C-u’: all) C-M-x - Toggle temporary/savable status of bookmark M-X - Toggle temporary/savable status of marked bookmarks M-x bmkp-delete-all-temporary-bookmarks - Delete all temp bookmarks x - Delete (visible) bookmarks flagged `D’ D - Delete (visible) bookmarks marked `>’
Bookmark Tags
Here:
T c - Copy tags from this bookmark (for subsequent pasting) T + - Add some tags to a bookmark T - - Remove some tags from a bookmark (`C-u’: from all bookmarks) T 0 - Remove all tags from a bookmark T d - Remove some tags from all bookmarks T r - Rename a tag in all bookmarks T l - List all tags used in any bookmarks (`C-u’: show tag values) T > l - List tags used in marked bookmarks (`C-u’: show tag values) T e - Edit bookmark’s tags T v - Set the value of a tag (as attribute)
T > v - Set value of a tag, for each marked bookmark (`C-u’: all) T > C-y - Add tags copied from a bookmark to those marked (`C-u’: all) T > q - Replace tags of marked with copied tags (`C-u’: all) T > + - Add some tags to the marked bookmarks (`C-u’: all) T > - - Remove some tags from the marked bookmarks (`C-u’: all)
T m % - Mark bookmarks having at least one tag that matches a regexp T m + - Mark bookmarks having at least one tag in a set (OR) T m * - Mark bookmarks having all of the tags in a set (AND) T m ~ + - Mark bookmarks not having any of the tags in a set (NOT OR) T m ~ * - Mark bookmarks not having all of the tags in a set (NOT AND)
T u % - Unmark bookmarks having a tag that matches a regexp T u + - Unmark bookmarks having at least one tag in a set (OR) T u * - Unmark bookmarks having all of the tags in a set (AND) T u ~ + - Unmark bookmarks not having any tags in a set (NOT OR) T u ~ * - Unmark bookmarks not having all tags in a set (NOT AND)
Anywhere:
C-x p t c - Copy tags from a bookmark (for subsequent pasting) C-x p t C-y - Add (paste) tags copied from a bookmark C-x p t q - Replace (paste) a bookmark’s tags with copied tags C-x p t V - Set a tag value for each bookmark in navlist C-x p t e - Edit a bookmark’s tags (prompt for the bookmark) C-x p t + a - Add tags to a file (create/update autofile bookmark) C-x p t - a - Remove tags from a file (an autofile bookmark)
M-x bmkp-bmenu-show-only-lighted-bookmarks - Show only the highlighted bookmarks M-x bmkp-bmenu-set-lighting - Set highlighting for bookmark M-x bmkp-bmenu-set-lighting-for-marked - Set highlighting for marked bookmarks M-x bmkp-bmenu-light - Highlight bookmark M-x bmkp-bmenu-unlight - Unhighlight bookmark M-x bmkp-bmenu-mark-lighted-bookmarks - Mark the highlighted bookmarks M-x bmkp-bmenu-light-marked - Highlight the marked bookmarks M-x bmkp-bmenu-unlight-marked - Unhighlight the marked bookmarks C-x p h - Highlight a bookmark in current buffer C-x p u - Unhighlight a bookmark in current buffer C-x p H - Highlight bookmarks (see prefix arg) C-x p U - Unhighlight bookmarks (see prefix arg) C-x p = - List bookmarks highlighted at point C-x p C-u - Unhighlight a bookmark at point or on same line j h - Jump to a highlighted bookmark (other window)
(Repeat to cycle normal/reversed/off, except as noted.)
s r - Reverse current sort direction (repeat to toggle) s C-r - Complement sort predicate decisions (repeat to toggle) s s - Cycle sort orders (repeat to cycle)
s > - Sort marked (`>’) bookmarks first s D - Sort flagged (`D’) bookmarks first s * - Sort modified (`*’) bookmarks first s t - Sort tagged (`t’) bookmarks first
s 0 - Sort by bookmark creation time s b - Sort by last buffer or file access s d - Sort by last bookmark access time s g - Sort by Gnus thread: group, article, message s i - Sort by Info manual, node, position s k - Sort by bookmark type s n - Sort by bookmark name s u - Sort by URL s v - Sort by bookmark visit frequency
s f d - Sort by last local file access s f k - Sort by local file type: 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)
. - Show all bookmarks > - Toggle showing only marked bookmarks < - Toggle showing only unmarked bookmarks
A S - Show only autofile bookmarks X S - Show only temporary bookmarks
B S - Show only non-file (i.e. buffer) bookmarks M-d M-s - Show only Dired bookmarks F S - Show only file & directory bookmarks (`C-u’: local only) G S - Show only Gnus bookmarks I S - Show only Info bookmarks i S - Show only Icicles search-hits bookmarks M-I M-S - Show only image-file bookmarks O S - Show only orphaned local file bookmarks (`C-u’: remote also) K S - Show only desktop bookmarks M S - Show only `man’ page bookmarks R S - Show only region bookmarks Q S - Show only function bookmarks M-u M-s - Show only URL bookmarks V S - Show only variable-list bookmarks T S - Show only tagged bookmarks M-x bmkp-bmenu-show-only-untagged-bookmarks - Show only untagged bookmarks W S - Show only W3M (URL) bookmarks w S - Show only snippet bookmarks Y S - Show only bookmark-file bookmarks Z S - Show only bookmark-list bookmarks
P A - Incrementally show bookmarks whose annotations match regexp P B - Incrementally show only bookmarks whose names match a regexp P F - Incrementally show only bookmarks whose files match a regexp P T - Incrementally show only bookmarks whose tags match a regexp
- S - Show (only) the omitted bookmarks
. - Show the un-omitted bookmarks (all)
- > - Omit the marked bookmarks; un-omit them if after `- S’
- U - Un-omit all omitted bookmarks
C-c C-c - Define a command to restore the current sort order & filter C-c C-S-c - Define a command to restore current bookmark list T s - Define a command to sort bookmarks by tags C-c C-j - Define a command to jump to a bookmark that is now marked
bookmark-bmenu-file-column - Bookmark width if files are shown bookmark-bmenu-toggle-filenames - Show filenames initially?
bmkp-bmenu-omitted-bookmarks - List of omitted bookmarks bmkp-bmenu-state-file - File to save bookmark-list state (“home”) nil: do not save/restore bmkp-sort-comparer - Initial sort bmkp-sort-orders-for-cycling-alist
- Sort orders that `s s’… cycles
bookmark-automatically-show-annotations - Show annotation when visit? bookmark-completion-ignore-case - Case-sensitive completion? bookmark-default-file - File to save bookmarks in bookmark-menu-length - Max size of bookmark-name menu item bookmark-save-flag - Whether and when to save bookmark-use-annotations - Query for annotation when saving? bookmark-version-control - Numbered backups of bookmark file?
bmkp-autoname-format - Format of autonamed bookmark name bmkp-last-as-first-bookmark-file - Whether to start with last b. file bmkp-crosshairs-flag - Highlight position when visit? bmkp-menu-popup-max-length - Use menus to choose bookmarks? bmkp-save-new-location-flag - Save if bookmark relocated? bmkp-sequence-jump-display-function - How to display a sequence bmkp-sort-comparer - Predicates for sorting bookmarks bmkp-su-or-sudo-regexp - Bounce-show each end of region? bmkp-this-file/buffer-cycle-sort-comparer - cycling sort for here bmkp-use-region - Activate saved region when visit? Send a Bookmark+ bug report: `\[bmkp-send-bug-report]’.