SiteMap Search ElispArea HowTo Glossary RecentChanges News Problems Suggestions
Yemen, National Day

Icicles - Bookmark Enhancements

iciclesimage
Previous: Icicles - Other Search CommandsIciclesIciclesIndexNext: Icicles - Emacs Tags Enhancements

Bookmark Enhancements

Many of the enhancements described on this page are available only if you also use library bookmark+.el (which I recommend). Bookmark+ is compatible with vanilla Emacs bookmarks across multiple Emacs versions. It enhances the use of bookmarks in many ways. The explanation here does not attempt to describe the Bookmark+ enhancements; it describes only the Icicles features that make use of them.

One of the main Bookmark+ enhancements is support for new bookmark types. Icicles provides type-specific bookmark commands and bookmark-candidate filtering.

In addition, when you complete the names of some kinds of objects, you can use ‘C-x m’ to choose objects of that type. For example, when you use ‘icicle-dired’ (‘C-x d’) to complete a directory name, you can use ‘C-x m’ to choose among your Dired bookmarks. See Accessing Saved Locations (Bookmarks) on the Fly.

Regardless of the bookmark type, another Bookmark+ feature that Icicles takes advantage of is the fact that a bookmark (any bookmark) can save not only a single position but a region, that is, two positions. You can think of this as bookmarking, or saving, regions. When you jump to a region bookmark, the region is activated (if option ‘bmkp-use-region’ is non-‘nil’).

These are the main Icicles bookmarking features:

Each is described in a little more detail below. More generally, however, the Bookmark+ doc is your friend.

Using Tagged Files

Bookmark+ lets you easily tag files with delicious-style tags of your choice. You need not visit the files to do this. Icicles makes this tagging even easier. Tagging a file creates an autofile bookmark that records the tags (metadata). Tags are generally strings, but you can also associate arbitrary EmacsLisp data with them. Besides tagging files, you can add tags to any kind of bookmark.

In Icicle mode, the Bookmark+ keys for tagging and untagging files are bound to multi-commands ‘icicle-tag-a-file’ and ‘icicle-untag-a-file’.

By default, these are on `C-x p t + a’ and ‘C-x p t - a’, respectively. The commands are actually bound to `+ a’ and ‘- a’ in keymap ‘bmkp-tags-map’, and you can of course bind that keymap to any key besides the default ‘C-x p t’. If you bind the keymap to ‘f2’, for instance, then `f2 + a’ and ‘f2 - a’ are all you need.

In addition, all Icicles file commands (and autofile bookmark commands) let you tag or untag files on the fly, during file-name completion, using the keys `C-x a +’ and ‘C-x a -’ respectively (‘a’ for autofile). Similarly, you can use ‘C-x a a’ during file-name completion to create an autofile bookmark for a file without tagging it.

All Icicles file commands also let you narrow the set of matching completions to those files that are tagged in certain ways, by using these keys on the fly:

For example:

  C-x 4 f foo TAB C-x C-t + red RET blue RET RET

‘TAB’ narrows the file-name candidates here to those starting with “foo”. `C-x C-t +’ prompts for one or more tags (”red” and “blue”), then it narrows the candidates to the names of files that are tagged either “red” or “blue” (or both).

You can of course use progressive completion, repeating `C-x C-t +’ to also require tag “yellow” or “purple”, for instance.

There are also several Icicles multi-commands for jumping to tagged files. They are all on the Bookmark+ keymaps ‘bmkp-jump-map’ and ‘bmkp-jump-other-window-map’: prefixes ‘C-x j a’ and ‘C-x 4 j a’(‘a’ for autofile). The latter is for the ‘-other-window’ version of each command.

See Also:

`icicle-find-file-tagged'

Command ‘icicle-find-file-tagged’ (‘C-x j t C-f C-f’) matches tags as part of a multi-completion completion candidate. Each candidate is composed of these fields: an absolute file name plus the file’s tags, all separated by `icicle-list-join-string’ ("^G^J", by default). As always, you can type ‘C-M-j’ to insert this separator into the minibuffer.

For this command, by default `.’ in your input matches any character, including a newline. As always, you can use `C-M-.’ to toggle this (so `.’ does not match newline).

You can match your input against the file name or tags or both. E.g., type:

That assumes that these tags do not also match any file names.

If you need to match against a particular field (e.g. the file name or a specific tag position), then use the field separator. Otherwise, just use progressive completion, as shown above.

E.g., to match only tags and not the filename, start with ‘C-M-j’ to get past the file-name field. To match both file name and tags, type something to match the file name before the ‘C-M-j’. E.g., type:

‘2011 C-M-j red S-SPC blue’ to match files tagged ‘red’ and ‘blue’ that have ‘2011’ in their names

Jumping to Tagged Files (Other)

The other Icicles commands for jumping to tagged files let you input a set of tags to match, or regexps, one by one. The commands differ only in how this set of patterns is used. There are commands that use the intersection of the matches and commands that use the union.

All of them work the same way: you enter a pattern to match followed by ‘RET’, ending with ‘RET RET’. Intersection is indicated by ‘*’ in the key binding. Union is indicated by `+’. The regexp-matching commands have `%’ in the key binding. And again, there is an ‘-other-window’ version of each, on prefix key ‘C-x 4 j t C-f’ instead of ‘C-x j t C-f’.

See these sections of the Bookmark+ doc for more information about bookmark tags:

Saving Regions and Selecting Them

Saving the region just means bookmarking it. As for any bookmark, it must have a name. When you later jump to a region bookmark, the region is activated (provided option ‘bmkp-use-region’ is non-‘nil’).

Icicles gives you quick ways to save a region and select (activate) a saved region. You can do both using ‘C-x C-x’.

Setting a Bookmark and Jumping to a Bookmark

Just as ‘C-x C-x’ lets you either set or jump to a region bookmark, so ‘C-x r m’ lets you either set or jump to any bookmark. ‘C-x r m’ is the vanilla Emacs key for setting a bookmark. In Icicle mode it is bound by default to command ‘icicle-bookmark-cmd’. (By default, whatever keys are normally bound to ‘bookmark-set’ are remapped in Icicle mode to ‘icicle-bookmark-cmd’.)

Jumping to a Bookmark

Icicles commands that jump to a bookmark are multi-commands: you can use them to jump to any number of bookmarks in a single invocation. Each jump command acts as a bookmark browser.

As with most Icicles tripping commands, after you jump to a (non-region) bookmark, the cursor position is highlighted using cross hairs, if you also use library crosshairs.el (see CrosshairHighlighting).

Bookmark names are highlighted in buffer ‘*Completions*’ to indicate the bookmark type. The faces used are those defined by Bookmark+.

If option `icicle-show-multi-completion-flag’ is non-‘nil’, then each completion candidate is a multi-completion, with up to three parts: the bookmark name, the bookmark file or buffer name, and any (delicious-style) tags the bookmark has. You can toggle option ‘icicle-show-multi-completion-flag’ (for the next command) using ‘M-m’ during completion.

When using multi-completion candidates, you can match any of the multi-completion parts. For example, you can match all bookmarks that have any tags by typing this when choosing a bookmark:

  C-M-j . * C-M-j S-TAB

Or match all bookmarks whose names match ‘P42’ and whose tags match ‘blue’:

  P 4 2 . * C-M-j . * C-M-j . * b l u e S-TAB

(Each ‘C-M-j’ inserts `^G\n’, which is `icicle-list-join-string’.)

‘C-M-RET’ shows detailed info about the current bookmark completion candidate. ‘C-u C-M-RET’ shows the complete, internal info for the bookmark. Likewise, for the other candidate help keys: ‘C-M-down’ etc. And the mode line always shows summary info about the current bookmark.

During bookmark completion you can sort the candidates in various bookmark-specific ways:

The most general Icicles jump commands are ‘icicle-bookmark’ and ‘icicle-bookmark-other-window’. In Icicle mode these are bound to whatever ‘bookmark-jump’ and ‘bookmark-jump-other-window’ are normally bound to. If you use Bookmark+, the default bindings are ‘C-x j j’ and ‘C-x 4 j j’, respectively.

When you use these commands, you can narrow the completion candidates to bookmarks of a specific type using the following keys:

These same keys are used at the top level for individual jump commands for bookmarks of each of each type. For example, `icicle-bookmark-info’ is bound to ‘C-x j i’. Other-window jump commands are the same, but use the prefix key ‘C-x 4 j’ instead of ‘C-x j’.

Commands ‘icicle-bookmark’ and ‘icicle-bookmark-other-window’ can use a cache for the set of available bookmarks. This improves performance, especially if you have a lot of bookmarks. The downside is that the list of completion candidates is not automatically updated when you add new bookmarks.

By default, this caching is off, so the set of possible bookmark candidates is always up-to-date. You can turn on this caching by setting option `icicle-bookmark-refresh-cache-flag’ to ‘nil’.

Alternatively, you can use a prefix argument to reverse the effect of this option. If you have a lot of bookmarks then I recommend that you customize the option to ‘nil’ and just update it occasionally by using ‘C-u’ for bookmark completion. That will temporarily turn off caching so that the current jump command refreshes (updates) the cache. The default value of the option is ‘t’ only to avoid confusion for new users.

The bookmarks cache is also used for searching bookmarks (see next). The type-specific bookmark jump commands (e.g. ‘icicle-bookmark-info-other-window’) do not use the cache, since they typically use a smaller number of candidates. And the cache is automatically updated whenever you use ‘S-delete’ to delete a candidate bookmark.

See Also: Icicles - Tripping.

Searching Bookmarked Objects

Icicles search (and replace) lets you search across multiple buffers, files, or bookmarks. This is true for nearly all Icicles search commands. You use a plain prefix argument to specify bookmark searching. For command ‘icicle-search’ itself (`C-u C-c `’), you can alternatively use the specific command ‘icicle-search-bookmarks-together’.

When you do this you first choose the bookmarks to search, using completion. Use ‘C-RET’ and similar multi-command actions to choose (use ‘RET’ for the final choice). Once you have chosen the bookmarks, you type a search pattern to narrow the set of candidates.

(Multi-command ‘icicle-bookmark-list’ similarly lets you choose bookmarks (or bookmark names, with a prefix arg). It returns them in a Lisp list.)

When you search the text of a region bookmark, the search is limited to the region.

If you use library Bookmark+, then marking bookmarks in buffer ‘*Bookmark List*’ is another way of choosing them for searching. Mode-specific Icicles search, ‘M-s M-s m’ (in this case, ‘icicle-search-bookmark-list-marked’) searches the marked objects, in this case the targets of the marked bookmarks. (You can similarly use ‘M-s M-s m’ in Ibuffer, BufferMenu, and Dired to search all marked buffers/files using Icicles search.)

In addition to using Icicles search on a set of bookmark targets together, you can use the following Icicles search [multi-commands that are specific to bookmarks:

‘icicle-search-bookmark’ is a general command; the others are each specific to a certain kind of bookmark candidate, and they need library Bookmark+. The last four let you search bookmarks that have a certain set of tags.

All of these commands act the same way. They are multi-commands, so you can use them to search multiple bookmarks. But unlike ‘icicle-search-bookmarks-together’ (`C-u C-c `’) and ‘icicle-search-bookmark-list-marked’ (‘M-s M-s m’), you do not first choose the bookmarks and then search them together. Instead, you search them one at a time, choosing each with a multi-command action.

‘icicle-search-bookmark’ is flexible, letting you specify any set of bookmarks to use as candidates. The candidates are the bookmarks last shown in the ‘*Bookmark List*’ display (list ‘bmkp-sorted-alist’, to be precise).

You can use the Bookmark+ features of ‘*Bookmark List*’ to limit the candidates to bookmarks of a certain type (e.g., only autofiles, using ‘A S’), bookmarks with certain tags (e.g., only those with tags matching a regexp using `T m %’ followed by `>’), and so on. Whatever set of bookmarks are shown (or were last shown) in ‘*Bookmark List*’ are the bookmarks to be searched.

See Also:


Previous: Icicles - Other Search CommandsIciclesIciclesIndexNext: Icicles - Emacs Tags Enhancements

DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryBookmarking CategoryCommands CategoryCompletion CategoryModes CategoryProgrammerUtils CategoryCode CategorySearchAndReplace CategoryShell CategoryRegion