: [[image:iciclesimage]] || *Previous:* [[Icicles - Other Search Commands]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[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 [[bookmark]]s 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 [[completion|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 [[Icicles - More About Multi-Commands#AccessingBookmarks|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: * Tagging files (a la [[http://delicious.com|delicious]]) and jumping to tagged files * Bookmarking the region and selecting a bookmarked region * Setting a bookmark and jumping to a bookmark * Searching the text of a bookmark's buffer or region * Saving sets of '''Icicles''' search hits as bookmarks -- "jump" to such a bookmark to restore the saved hits during a later search. * Applying an arbitrary function to any bookmark property Each is described in a little more detail below. More generally, however, the '''Bookmark+''' doc is your friend. [:TaggingFiles] [:UsingTaggedFiles] == Using Tagged Files== '''Bookmark+''' lets you easily tag files with [[http://delicious.com|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 [[BookmarkPlus#AutofileBookmarks|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-command]]s '''`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''' [[Icicles - File-Name Input|file commands]] (and [[BookmarkPlus#AutofileBookmarks|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: * '''`##C-x C-t *##'''' -- files having all of the tags you specify * '''`##C-x C-t +##'''' -- files having some of the tags you specify * '''`##C-x C-t % *##'''' -- files having all of their tags matching a regexp * '''`##C-x C-t % +##'''' -- files having some of their tags matching a regexp 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-command]]s 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:''' * [[Icicles - Nutshell View#ThirdExampleTaggedFiles|Nutshell View - Tagged Files]] * [[Icicles - File-Name Input#KeysBoundDynamicallyForFileNameInput|Action Keys Bound Dynamically During File-Name Input]] * [[#icicle-find-file-tagged|icicle-find-file-tagged]], next, for an alternative way to narrow file-name candidates based on tags [:icicle-find-file-tagged] [:icicle-find-file-tagged-other-window] === `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 '''`[[Icicles - Customization and General Tips#icicle-list-join-string|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: * `##red S-TAB##' to match files with the tag `red' * `##red S-SPC green S-SPC blue##' to match files with tags `red', `green', and `blue' (in any order) 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 [[Icicles - Progressive Completion|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 (Command '''`icicle-bookmark-tagged'''' ('''`C-x j t j'''') acts the same as `icicle-find-file-tagged', but for all tagged bookmarks, not just autofiles.) [:icicle-find-file-all-tags] [:icicle-find-file-all-tags-other-window] [:icicle-find-file-all-tags-regexp] [:icicle-find-file-all-tags-regexp-other-window] [:icicle-find-file-some-tags] [:icicle-find-file-some-tags-other-window] [:icicle-find-file-some-tags-regexp] [:icicle-find-file-some-tags-regexp-other-window] === Jumping to Tagged Files (Other) === The other '''Icicles''' commands for jumping to tagged files let you input a set of tags to match, or [[regexp]]s, 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''''. * '''`icicle-find-file-all-tags'''' ('''`##*##'''') -- Match each tag exactly * '''`icicle-find-file-all-tags-regexp'''' ('''`##% *##'''') -- Regexp-match each tag * '''`icicle-find-file-some-tags'''' ('''`##+##'''') -- Match some tag (>= 1) exactly * '''`icicle-find-file-some-tags-regexp'''' ('''`##% *##'''') -- Regexp-match some tag(s) See these sections of the '''Bookmark+''' doc for more information about bookmark tags: * [[BookmarkPlus#BookmarkTags|Bookmark Tags]] * [[BookmarkPlus#AutofileBookmarks|Autofile Bookmarks]] * [[BookmarkPlus#TagCommandsAndKeys|Tag Commands and Keys]] * [[BookmarkPlus#BookmarkTagSets|Tags: Sets of Bookmarks]] * [[BookmarkPlus#TagsAsAttributes|Bookmark Tags Can Have Values]] [:SavingAndSelectingRegions] == 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''''. * With ''no'' prefix argument or with a ''single plain'' prefix argument ('''`C-u''''), `C-x C-x' acts the same as for vanilla Emacs: it exchanges point and mark, activating the region or not depending on the use of `C-u' and whether you are in TransientMarkMode. * With a ''multiple plain'' prefix argument ('''`C-u C-u''''), `C-x C-x' jumps to a region bookmark that you choose using completion, and activates it. (See also '''Icicles''' tripping commands '''`icicle-select-zones'''' and '''`icicle-buffer-narrowing'''', which let you trip among [[buffer]] zones, selecting them as the [[region]] and [[narrowing]] to them, respectively. * With a ''numeric'' prefix argument, `C-x C-x' saves the region. If the prefix argument is ''negative'', then you are prompted for the name to use. Otherwise, the bookmark is ''named automatically'' using the ''buffer'' name plus '''`##: ##'''' plus the first '''`[[Icicles - Customization and General Tips#icicle-bookmark-name-length-max|icicle-bookmark-name-length-max]]'''' characters of the region text. (Newline characters are changed to spaces for the name.) So if (a) you are visiting buffer `foo', (b) the region text starts with "Arise, you wretched of the earth! For justice thunders condemnation: A better world's in birth!", and (c) the value of option '''`[[Icicles - Customization and General Tips#icicle-bookmark-name-length-max|icicle-bookmark-name-length-max]]'''' is 15, then `C-9 C-x C-x' sets the region bookmark named "'''foo: Arise, you''''". [:SettingOrJumpingToABookmark] == 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' and `bmkp-bookmark-set-confirm-overwrite' (from library '''[[Bookmark+]]''') are remapped in ''Icicle'' mode to `icicle-bookmark-cmd'. * With ''no'' prefix argument or a ''plain'' prefix argument (`C-u'), `C-x r m' acts like '''`icicle-bookmark-set''''. This is similar to `bookmark-set', but if you use '''[[Bookmark+]]''' then you can use (lax) [[completion]], choosing from existing bookmarks for the same buffer. This makes it easy to update a nearby bookmark. The same completion enhancements are available as for bookmark jumping -- see [[#JumpingToABookmark|Jumping to a Bookmark]], below. * With a ''negative'' prefix argument, `C-x r m' jumps to a bookmark (with completion). See [[#JumpingToABookmark|Jumping to a Bookmark]], below. * With a ''non-negative'' prefix argument, `C-x r m' sets a bookmark, automatically naming it. This is like the automatic naming for a region bookmark, except that instead of including a prefix of the ''region'' text, the name includes text from the ''current line'' that starts at [[point]]. So if the cursor in buffer `foo' is on the `y' in a line with the text "Arise, you wretched of the earth!", then the bookmark will automatically be named "'''foo: you wretch'''". If the prefix argument is ''0'', then the new bookmark does not overwrite any existing bookmark with the same name. [:JumpingToABookmark] == Jumping to a Bookmark == '''Icicles''' commands that jump to a bookmark are [[multi-command]]s: 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'' [[Icicles - Tripping|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 '''`[[Icicles - Customization and General Tips#icicle-show-multi-completion-flag|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 ([[http://delicious.com|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 '''`[[Icicles - Customization and General Tips#icicle-list-join-string|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: * By the current (latest) `##*Bookmark List*##' order * By bookmark name * By last access as a bookmark (date + time) * By bookmark visit frequency (number of times visited) * By last buffer or file access (date + time) * With marked bookmarks before unmarked (in `##*Bookmark List*##') * By file name * By (local) file type * By (local) file size * By last (local) file access (date + time) * By last (local) file update (date + time) * By Info location (manual and node) * By Gnus thread * By URL * By bookmark type 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: * '''`C-x j b'''' -- non-file ('''b'''uffer) bookmarks * '''`C-x j B'''' -- '''B'''ookmark-list bookmarks * '''`C-x j d'''' -- '''d'''ired bookmarks * '''`C-x j f'''' -- '''f'''ile bookmarks * '''`##C-x j . f##'''' -- file bookmarks for the current directory (think '''`.'''' as in UNIX) * '''`C-x j g'''' -- '''g'''nus bookmarks * '''`C-x j i'''' -- '''i'''nfo bookmarks * '''`C-x j M-i'''' -- '''i'''mage bookmarks * '''`C-x j K'''' -- des'''K'''top bookmarks * '''`C-x j l'''' -- '''l'''ocal-file bookmarks * '''`C-x j m'''' -- '''m'''an' pages * '''`C-x j n'''' -- remote-file bookmarks ('''n'''etwork) * '''`C-x j r'''' -- bookmarks with '''r'''egions * '''`C-x j u'''' -- '''u'''rl bookmarks * '''`C-x j w'''' -- '''w'''3m bookmarks * '''`C-x j x'''' -- temporary bookmarks * '''`C-x j y'''' -- bookmark-file bookmarks * '''`##C-x , ,##'''' -- bookmarks for the current buffer * '''`##C-x = b##'''' -- bookmarks for a specific '''b'''uffer * '''`##C-x = f##'''' -- bookmarks for a specific '''f'''ile These same keys are used at the top level for individual ''jump'' commands for bookmarks of each of each type. For example, `icicle-bookmark-'''i'''nfo' 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 '''`[[Icicles - Customization and General Tips#icicle-bookmark-refresh-cache-flag|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]]. [:SearchingBookmarkedObjects] == 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 argument). 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'''' * '''`icicle-search-autofile-bookmark'''' * '''`icicle-search-bookmark-list-bookmark'''' * '''`icicle-search-dired-bookmark'''' * '''`icicle-search-file-bookmark'''' * '''`icicle-search-gnus-bookmark'''' * '''`icicle-search-info-bookmark'''' * '''`icicle-search-local-file-bookmark'''' * '''`icicle-search-man-bookmark'''' * '''`icicle-search-non-file-bookmark'''' * '''`icicle-search-region-bookmark'''' * '''`icicle-search-remote-file-bookmark'''' * '''`icicle-search-specific-buffers-bookmark'''' * '''`icicle-search-specific-files-bookmark'''' * '''`icicle-search-this-buffer-bookmark'''' * '''`icicle-search-url-bookmark'''' * '''`icicle-search-w3m-bookmark'''' * '''`icicle-search-all-tags-bookmark'''' * '''`icicle-search-all-tags-regexp-bookmark'''' * '''`icicle-search-some-tags-bookmark'''' * '''`icicle-search-some-tags-regexp-bookmark'''' `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-command]]s, 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:''' * [[Icicles - Search Commands, Overview]] for more information about command `icicle-search' * [[#JumpingToABookmark]] for information about bookmark caching. Caching is also used for bookmark searching. * [[Icicles - Support for Projects]] [:BookmarkingIciclesSearchHits] == Bookmarking Icicles Search Hits == When you use '''Icicles''' search (of any kind), you can use '''`C-x C-M->'''' to save the current set of completion candidates (search hits) as an '''Icicles''' search-hits bookmark. "Jumping" to such a bookmark during '''Icicles''' search (of anything) restores those search hits: '''`C-x C-M-<'''' replaces the current search hits with them, and '''`C-x C-<'''' adds them to the set of current search hits. [:ActingOnBookmarkProperties] == Acting On Bookmark Properties == An Emacs bookmark record is a list with the bookmark name as [[car]] and a list of bookmark properties as [[cdr]] -- see variable `bookmark-alist' for a description of the commonly used properties. When you use an '''Icicles''' command that reads a bookmark name, you can use `C-S-RET' (`icicle-candidate-alt-action') to apply a function to any property of the current bookmark candidate. You are prompted for the function and the property. You choose the target property using completion from among those available for the current bookmark candidate. Remember that you can use `C-M-RET' to see a description of the bookmark, which typically describes its most important properties. You can choose any function symbol using completion, or you can enter a lambda expression. The function chosen must accept the particular property value or else you will see an error message. The value returned by the function is pretty-printed. If the function you choose is `identity' then the action just pretty-prints the property value, which can be useful, even if trivial. If you use '''`Bookmark+'''', `C-M-RET' can be particularly useful for acting on [[BookmarkPlus#BookmarkTags|bookmark tags]] or on the text of a [[BookmarkPlus#SnippetBookmarks|snippet bookmark]]. ---- || *Previous:* [[Icicles - Other Search Commands]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Emacs Tags Enhancements]] || DrewsElispLibraries referenced here: Lisp:icicles.el CategoryBookmarking CategoryCommands CategoryCompletion CategoryModes CategoryProgrammerUtils CategoryCode CategorySearchAndReplace CategoryShell CategoryRegion