1 ;;; bookmark+-doc.el - Documentation for package Bookmark+.
3 ;; Filename: bookmark+-doc.el
4 ;; Description: Documentation for package Bookmark+
6 ;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
7 ;; Copyright (C) 2000-2011, Drew Adams, all rights reserved.
8 ;; Created: Fri Sep 15 07:58:41 2000
9 ;; Last-Updated: Sun Aug 7 14:14:44 2011 (-0700)
12 ;; URL: http://www.emacswiki.org/cgi-bin/wiki/bookmark+-doc.el
13 ;; Keywords: bookmarks, bookmark+, placeholders, annotations, search,
14 ;; info, url, w3m, gnus
15 ;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x
17 ;; Features that might be required by this library:
21 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
25 ;; Documentation for the Bookmark+ package, which provides
26 ;; extensions to standard library `bookmark.el'.
28 ;; The Bookmark+ libraries are these:
30 ;; `bookmark+.el' - main (driver) library
31 ;; `bookmark+-mac.el' - Lisp macros
32 ;; `bookmark+-lit.el' - (optional) code for highlighting bookmarks
33 ;; `bookmark+-bmu.el' - code for the `*Bookmark List*' (bmenu)
34 ;; `bookmark+-1.el' - other required code (non-bmenu)
35 ;; `bookmark+-key.el' - key and menu bindings
37 ;; `bookmark+-doc.el' - documentation (comment-only - this file)
38 ;; `bookmark+-chg.el' - change log (comment-only file)
40 ;; The documentation includes how to byte-compile and install
41 ;; Bookmark+. It is also available in these ways:
43 ;; 1. From the bookmark list (`C-x r l'):
44 ;; Use `?' to show the current bookmark-list status and general
45 ;; help, then click link `Doc in Commentary' or link `Doc on the
48 ;; 2. From the Emacs-Wiki Web site:
49 ;; http://www.emacswiki.org/cgi-bin/wiki/BookmarkPlus.
51 ;; 3. From the Bookmark+ group customization buffer:
52 ;; `M-x customize-group bookmark-plus', then click link
55 ;; (The commentary links in #1 and #3 work only if put you this
56 ;; library, `bookmark+-doc.el', in your `load-path'.)
58 ;; More description below.
63 ;; On 2010-06-18, I changed the prefix used by package Bookmark+
64 ;; from `bookmarkp-' to `bmkp-'. THIS IS AN INCOMPATIBLE CHANGE.
65 ;; I apologize for the inconvenience, but the new prefix is
66 ;; preferable for a number of reasons, including easier
67 ;; distinction from standard `bookmark.el' names.
69 ;; This change means that YOU MUST MANUALLY REPLACE ALL
70 ;; OCCURRENCES of `bookmarkp-' by `bmkp-' in the following
71 ;; places, if you used Bookmark+ prior to this change:
73 ;; 1. In your init file (`~/.emacs') or your `custom-file', if
74 ;; you have one. This is needed if you customized any
75 ;; Bookmark+ features.
77 ;; 2. In your default bookmark file, `bookmark-default-file'
78 ;; (`.emacs.bmk'), and in any other bookmark files you might
81 ;; 3. In your `*Bookmark List*' state file,
82 ;; `bmkp-bmenu-state-file' (`~/.emacs-bmk-bmenu-state.el').
84 ;; 4. In your `*Bookmark List*' commands file,
85 ;; `bmkp-bmenu-commands-file' (`~/.emacs-bmk-bmenu-commands.el'),
88 ;; You can do this editing in a virgin Emacs session (`emacs
89 ;; -Q'), that is, without loading Bookmark+.
91 ;; Alternatively, you can do this editing in an Emacs session
92 ;; where Bookmark+ has been loaded, but in that case you must
93 ;; TURN OFF AUTOMATIC SAVING of both your default bookmark file
94 ;; and your `*Bookmark List*' state file. Otherwise, when you
95 ;; quit Emacs your manually edits will be overwritten.
97 ;; To turn off this automatic saving, you can use `M-~' and `M-l'
98 ;; in buffer `*Bookmark List*' (commands
99 ;; `bmkp-toggle-saving-bookmark-file' and
100 ;; `bmkp-toggle-saving-menu-list-state' - they are also in the
101 ;; `Bookmark+' menu).
104 ;; Again, sorry for this inconvenience.
111 ;; If you have library `linkd.el' and Emacs 22 or later, load
112 ;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
113 ;; navigate around the sections of this doc. Linkd mode will
114 ;; highlight this Index, as well as the cross-references and section
115 ;; headings throughout this file. You can get `linkd.el' here:
116 ;; http://dto.freeshell.org/notebook/Linkd.html.
118 ;; (@> "Documentation")
119 ;; (@> "Installing Bookmark+")
120 ;; (@> "Bookmark+ Features")
121 ;; (@> "Different Types of Jump Commands")
122 ;; (@> "Bookmark Tags")
123 ;; (@> "Bookmark Tags Can Have Values")
124 ;; (@> "Function, Sequence, and Variable-List Bookmarks")
125 ;; (@> "Editing Bookmarks")
126 ;; (@> "Bookmark-List Views - Saving and Restoring State")
127 ;; (@> "Quitting Saves the Bookmark-List State")
128 ;; (@> "State-Restoring Commands and Bookmarks")
129 ;; (@> "Bookmarking without Visiting the Target")
130 ;; (@> "Bookmarking a File or a URL")
131 ;; (@> "Autofile Bookmarks")
132 ;; (@> "Bookmarking the Marked Files in Dired")
133 ;; (@> "Bookmarking Compilation, Grep, and Occur Hits")
134 ;; (@> "Bookmarking Files That You Cannot Visit")
135 ;; (@> "Opening Bookmarks Using Windows File Associations")
136 ;; (@> "Using Multiple Bookmark Files")
137 ;; (@> "Bookmark-File Bookmarks")
138 ;; (@> "The Bookmark List (Display)")
139 ;; (@> "Tag Commands and Keys")
140 ;; (@> "Tags: Sets of Bookmarks")
141 ;; (@> "Open Dired for the Marked File Bookmarks")
142 ;; (@> "Marking and Unmarking Bookmarks")
143 ;; (@> "Filtering Bookmarks (Hiding and Showing)")
144 ;; (@> "Only Visible Bookmarks Are Affected")
145 ;; (@> "Omitting Bookmarks from Display")
146 ;; (@> "Sorting Bookmarks")
147 ;; (@> "Bookmarks for Specific Files or Buffers")
148 ;; (@> "Cycling, Navigation List, Autonaming")
149 ;; (@> "The Bookmark Navigation List")
150 ;; (@> "Cycling the Navigation List")
151 ;; (@> "Cycling Dynamic Sets of Bookmarks")
152 ;; (@> "Cycling in the Current Buffer")
153 ;; (@> "Autonamed Bookmarks - Easy Come Easy Go")
154 ;; (@> "Highlighting Bookmark Locations")
155 ;; (@> "Defining How to Highlight")
156 ;; (@> "Highlighting On Demand")
157 ;; (@> "Highlighting Automatically")
158 ;; (@> "Using Highlighted Bookmarks")
159 ;; (@> "Use Bookmark+ with Icicles")
160 ;; (@> "If you use Emacs 20 and Also a More Recent Version")
161 ;; (@> "Bookmark Compatibility with Vanilla Emacs (`bookmark.el')")
162 ;; (@> "New Bookmark Structure")
164 ;;(@* "Documentation")
169 ;;(@* "Installing Bookmark+")
170 ;; ** Installing Bookmark+ **
172 ;; The main Bookmark+ library is `bookmark+.el'. The other required
173 ;; libraries are `bookmark+-mac.el', `bookmark+-bmu.el',
174 ;; `bookmark+-1.el', and `bookmark+-key.el'. If you want to be able
175 ;; to highlight bookmarks then you will also need library
176 ;; `bookmark+-lit.el'. I recommend that you byte-compile all of the
177 ;; libraries, after loading the source files (in particular, load
178 ;; `bookmark+-mac.el').
180 ;; Put the directory of these libraries in your `load-path' and add
181 ;; this to your init file (~/.emacs):
183 ;; (require 'bookmark+)
185 ;; That will load all of the Bookmark+ libraries. If you do not care
186 ;; about bookmark highlighting then simply do not put
187 ;; `bookmark+-lit.el' in your `load-path'.
189 ;; By default (see option `bmkp-crosshairs-flag'), when you visit a
190 ;; bookmark that has no region it is highlighted temporarily using
191 ;; crosshairs, for easy recognition. (This temporary highlighting is
192 ;; independent of the highlighting provided by `bookmark+-lit.el'.)
194 ;; For this optional crosshairs feature you also need library
195 ;; `crosshairs.el', which in turn requires libraries `col-highlight',
196 ;; `hl-line', `hl-line+', and `vline'. Library `hl-line' comes with
197 ;; vanilla Emacs. The others are available from the Emacs Wiki web
198 ;; site: http://www.emacswiki.org/. You also need Emacs 22 or later
201 ;;(@* "Bookmark+ Features")
202 ;; ** Bookmark+ Features **
204 ;; Here is an overview of some of the features that Bookmark+
205 ;; provides. Some of these are detailed in other sections, below.
207 ;; * Richer bookmarks. They record more. They are more accurate.
209 ;; - You can tag bookmarks, a la del.icio.us. In effect, tags
210 ;; define bookmark sets. A bookmark can have any number of
211 ;; tags, and multiple bookmarks can have the same tag. You can
212 ;; sort, show/hide, or mark bookmarks based on their tags.
214 ;; - Bookmark+ tags can be more than just names. They can be
215 ;; full-fledged user-defined attributes, with Emacs-Lisp objects
218 ;; - You can have multiple bookmarks with the same name. This is
219 ;; particularly useful for autofile bookmarks, which are
220 ;; bookmarks that have the same name as their target files.
221 ;; They give you the effect of using files themselves as
222 ;; bookmarks. In particular, they let you, in effect, tag
223 ;; files. See (@> "Autofile Bookmarks") and
224 ;; (@> "Tagging Files").
226 ;; (In vanilla Emacs you can also, in theory, have multiple
227 ;; bookmarks with the same name. But you cannot really use them
228 ;; in any practical way. Vanilla Emacs cannot distinguish among
229 ;; them: the most recent one shadows all others with the same
232 ;; - Bookmarks record the number of times you have visited them
233 ;; and the time of the last visit. You can sort, show/hide, or
234 ;; mark bookmarks based on this info.
236 ;; - You can combine bookmarks, to make composite, or sequence,
237 ;; bookmarks. Invoking a sequence bookmark invokes each of its
238 ;; component bookmarks in turn. A component bookmark can itself
239 ;; be a sequence bookmark.
241 ;; - You can bookmark a region of text, not just a position. When
242 ;; you jump to a bookmark that records a region, the region is
243 ;; activated (see option `bmkp-use-region'). (Region activation
244 ;; is not supported for Gnus bookmarks.)
246 ;; - Bookmarks are relocated better than for vanilla Emacs when
247 ;; the contextual text changes.
249 ;; * Additional types of bookmarks.
251 ;; - Autofile bookmarks. You can bookmark a file without visiting
252 ;; it or naming the bookmark. The bookmark name is the same as
253 ;; the file name (non-directory part). You can have multiple
254 ;; such bookmarks with the same name, to bookmark files with the
255 ;; same name but in different directories.
257 ;; - Dired bookmarks. You can bookmark a Dired buffer, recording
258 ;; and restoring its `ls' switches, which files are marked,
259 ;; which subdirectories are inserted, and which (sub)directories
262 ;; - Bookmark-list bookmarks. You can bookmark the current state
263 ;; of buffer `*Bookmark List*' - a list of bookmarks. Jumping
264 ;; to such a bookmark restores the recorded sort order, filter,
265 ;; title, and omit list. See (@> "Omitting Bookmarks from Display").
267 ;; - Bookmark-file bookmarks. You can bookmark a bookmark file.
268 ;; Jumping to such a bookmark loads the bookmarks in the file.
269 ;; See (@> "Bookmark-File Bookmarks").
271 ;; - Desktop bookmarks. You can bookmark the current Emacs
272 ;; desktop, as defined by library `desktop.el' - use command
273 ;; `bmkp-set-desktop-bookmark' (`C-x p K'). You can "jump" to
274 ;; (that is, restore) a saved desktop. A desktop includes:
276 ;; - Some global variables. To exclude variables normally
277 ;; saved, see option `bmkp-desktop-no-save-vars'.
278 ;; - The current set of buffers and their associated files.
279 ;; For each: its mode, point, mark, & some local variables.
281 ;; - Gnus bookmarks. You can bookmark a Gnus article, a URL, a
282 ;; PDF file (DocView), a UNIX manual page (from the output of
283 ;; Emacs command `man' or `woman'), an image, or a piece of
286 ;; - Non-file (buffer) bookmarks. You can bookmark a buffer that
287 ;; is not associated with a file.
289 ;; - Function bookmarks. A bookmark can represent a Lisp
290 ;; function, which is invoked when you "jump" to the bookmark.
292 ;; - Sequence (composite) bookmarks. A bookmark can represent a
293 ;; sequence of other bookmarks.
295 ;; - Lisp variable bookmarks. A bookmark can represent a set of
296 ;; variables and their values.
298 ;; In particular, note that you can use the following kinds of
299 ;; bookmarks to quickly switch among different projects (sets of
300 ;; bookmarks): Dired, bookmark-list, bookmark-file, and desktop
303 ;; * Additional ways to bookmark.
305 ;; - You can bookmark the file or URL named at point (or any other
306 ;; file or URL), without first visiting it.
308 ;; - You can bookmark the targets of the hits in a compilation
309 ;; buffer or an `occur' buffer, without first visiting them.
311 ;; - You can bookmark all of the marked files in Dired at once.
313 ;; * Extensive menus.
315 ;; - In the `*Bookmark List*' display, a `mouse-3' popup menu has
316 ;; actions for the individual bookmark that you point to when
317 ;; you click the mouse.
319 ;; - In the `*Bookmark List*' display, a complete menu-bar menu,
320 ;; `Bookmark+', is available. The same menu is available on
321 ;; `C-mouse-3'. It has submenus `Jump To', `Mark', `Omit',
322 ;; `Show', `Sort', `Tags', `Highlight' (needs library
323 ;; `bookmark+-lit.el), and `Define Command'.
325 ;; - The vanilla `Bookmarks' menu, which is typically a submenu of
326 ;; the menu-bar `Edit' menu, is modified by adding several items
327 ;; from the `Bookmark+' menu, including submenus `Jump To',
328 ;; `Tags', and `Highlight'.
330 ;; * Improvements for the bookmark list.
332 ;; This is buffer `*Bookmark List*', aka the bookmark "menu list"
333 ;; (a misnomer), which you display using `C-x r l'. See
334 ;; (@> "The Bookmark List (Display)").
336 ;; - The last display state is saved (by default), and is restored
337 ;; the next time you show the list. (Tip: Use the bookmark list
338 ;; as your "Home" page at Emacs startup.)
340 ;; - You can save the current bookmark-list state at any time and
341 ;; return to it later. There are a few ways to do this,
342 ;; including bookmarking the list itself.
343 ;; See (@> "Bookmark-List Views - Saving and Restoring State").
345 ;; - Marking/unmarking is enhanced. It is similar to Dired's.
347 ;; - You can easily mark or show different classes of bookmarks.
349 ;; - Faces distinguish bookmarks by type.
351 ;; - You can sort bookmarks in many ways. You can easily define
352 ;; your own sort orders, even complex ones.
354 ;; - You can regexp-search (`M-a') or query-replace (`M-q') the
355 ;; targets (destination file or buffers) of the marked
356 ;; bookmarks, in the current bookmark-list sort order. For
357 ;; Emacs 23 and later, you can even search incrementally (`M-s a
358 ;; C-s', or `M-s a C-M-s' for regexp).
360 ;; - You can use `M-d >' to open Dired for just the local file
361 ;; bookmarks that are marked (`>').
363 ;; - If you use Emacs on Microsoft Windows, you can open bookmarks
364 ;; according to Windows file associations. (You will also need
365 ;; library `w32-browser.el'.)
367 ;; - You can use (lax) completion when you set a bookmark using
368 ;; `bookmark-set' (`C-x r m'), choosing from existing bookmarks
369 ;; for the same buffer. This makes it easy to update a nearby
370 ;; bookmark (e.g. relocate it). With a numeric prefix argument
371 ;; (or if there are no bookmarks for the buffer), you can choose
372 ;; from all bookmarks.
374 ;; - You can edit a bookmark: its name and file name/location, its
375 ;; tags, or its complete defining internal Lisp record.
377 ;; * Multiple bookmark files.
379 ;; - Although vanilla Emacs lets you load different bookmark
380 ;; files, this feature is not well supported, if not
381 ;; contradictory. With Bookmark+ you can easily (a) switch
382 ;; among alternative bookmark files or (b) load multiple files
383 ;; into the same session, accumulating their bookmark
384 ;; definitions. The last file you used is the default, so it is
385 ;; easy to go back and forth between two bookmark files.
386 ;; See (@> "Using Multiple Bookmark Files").
388 ;; * Type-specific jump commands.
390 ;; - When you want to jump to a bookmark of a specific type
391 ;; (e.g. Dired), you can use a command that offers only such
392 ;; bookmarks as completion candidates.
394 ;; * Dedicated keymaps as prefix keys.
396 ;; - Prefix `C-x p' is used for bookmark keys, in general. The
397 ;; vanilla keys on prefix `C-x r' are still available also, but
398 ;; that prefix is shared with register commands, making it less
399 ;; convenient for bookmarks. Using `C-x p' lets you focus on
402 ;; - Prefix `C-x p c' is for setting various kinds of bookmarks.
404 ;; - Prefixes `C-x j' and `C-x 4 j' (for other-window) are used
405 ;; for bookmark jump commands. Again, a dedicated prefix key
406 ;; helps you focus on one kind of action (jumping).
408 ;; All of these prefix keys correspond to prefix-map variables, so
409 ;; you need not use these particular prefixes. You can bind these
410 ;; maps to any prefix keys you want. These are the maps, together
411 ;; with their predefined bindings. (Note that the keymap for
412 ;; setting bookmarks is bound to a prefix in `bookmark-map'.)
414 ;; `bookmark-map' - `C-x p'
415 ;; `bmkp-set-map' - `C-x p c'
416 ;; `bmkp-jump-map' - `C-x j'
417 ;; `bmkp-jump-other-window-map' - `C-x 4 j'
419 ;; In addition, mode-specific bookmarking commands are bound in
420 ;; some other modes: Occur, Compilation (including Grep),
421 ;; Buffer-menu, Gnus, Info, Man, Woman, W3M, and Dired (if you use
422 ;; Dired+). These keys let you set or jump to bookmarks specific
427 ;; - Information about individual bookmarks.
429 ;; . Anywhere in Emacs, `C-x p ?' (command
430 ;; `bmkp-describe-bookmark') describes any bookmark. With a
431 ;; prefix argument, it shows you the full information that
432 ;; defines it (internal form).
434 ;; . In the bookmark list, `C-h RET' (or `C-h C-RET') describes
435 ;; the bookmark under the cursor. The description is as
436 ;; complete as possible - for example, for an image-file
437 ;; bookmark the complete EXIF image metadata is shown. (This
438 ;; is only for Emacs 22 and later, and only if you have
439 ;; command-line tool `exiftool' installed. See standard Emacs
440 ;; library `image-dired.el' for more information about
443 ;; And again, a prefix arg (`C-u C-h RET') means show the full
444 ;; (internal) bookmark information.
446 ;; - General Bookmark+ documentation.
448 ;; . Anywhere in Emacs, `M-x bmkp-bmenu-mode-status-help' shows
449 ;; detailed information about the current state of the
450 ;; bookmark list. Click button `Doc in Commentary' or button
451 ;; `Doc on the Web' to access the complete documentation.
453 ;; (Use button `Customize' to customize all '''Bookmark+'''
454 ;; faces and options.)
456 ;; . In the bookmark list, `?' and `C-h m' are the same as `M-x
457 ;; bmkp-bmenu-mode-status-help'. (`C-h m' in the bookmark
458 ;; list does not show you info about minor modes. If you want
459 ;; that, use `M-x describe-mode'.)
461 ;; . In the `bookmark-plus' group customization buffer (`M-x
462 ;; customize-group bookmark-plus'), click button `Commentary'.
464 ;; . From the Emacs-Wiki Web site,
465 ;; http://www.emacswiki.org/cgi-bin/wiki/BookmarkPlus.
467 ;; * Jump-destination highlighting.
469 ;; - When you jump to a bookmark, the destination (position) is
470 ;; highlighted temporarily using crosshairs, to make it stand
471 ;; out. Option `bmkp-crosshairs-flag' controls this, and this
472 ;; feature is available only if you also use library
475 ;; * Visual bookmarks (highlighting).
477 ;; - You can highlight the locations of bookmarks, either
478 ;; automatically or on demand. You control what kind of
479 ;; highlighting, if any, is used for which bookmarks. This
480 ;; feature requires that you have library `bookmark+-lit.el' in
481 ;; your `load-path' (it will then be loaded by `bookmark+.el).
483 ;; * Synergy with Icicles.
485 ;; - Icicles works with Bookmark+ to provide enhanced bookmark
486 ;; jumping (visiting), setting, and help. It gives you a
487 ;; bookmark browser. See (@> "Use Bookmark+ with Icicles") and
488 ;; http://www.emacswiki.org/cgi-bin/wiki/Icicles.
490 ;;(@* "Different Types of Jump Commands")
491 ;; ** Different Types of Jump Commands **
493 ;; When you jump to a bookmark, you can use completion to specify the
494 ;; bookmark name. `bookmark-jump' and `bookmark-jump-other-window',
495 ;; bound to `C-x j j' and `C-x 4 j j', are general commands. Their
496 ;; completion candidates include all of your bookmarks. With
497 ;; Bookmark+ you can easily have a large number of bookmarks.
499 ;; To provide more specificity, Bookmark+ provides many different
500 ;; bookmark jump commands. If you want to jump to a bookmark of a
501 ;; specific type, such as Info, you can use a Bookmark+ command that
502 ;; is specific to bookmarks of that type: only those bookmarks are
503 ;; completion candidates.
505 ;; There are thus type-specific commands: `bmkp-dired-jump',
506 ;; `bmkp-info-jump', and so on, bound to `C-x j d', `C-x j i', and so
507 ;; on. There are also commands to jump to bookmarks for the current
508 ;; buffer or for particular buffers or files
509 ;; (see (@> "Bookmarks for Specific Files or Buffers")).
511 ;; All bookmark jump commands are bound to keys that have the prefix
512 ;; `C-x j'. There is an other-window version of most jump commands,
513 ;; and it is bound to the same key as the same-window command, except
514 ;; the prefix is `C-x 4 j', not `C-x j'. For instance,
515 ;; `bmkp-dired-jump-other-window' is bound to `C-x 4 j d'.
517 ;; More precisely, the bookmark jump commands are on the prefix maps
518 ;; `bmkp-jump-map' and `bmkp-jump-other-window-map', which have the
519 ;; default bindings `C-x j' and `C-x 4 j'. You can bind these maps
520 ;; to any keys you like.
522 ;; If you do not remember the different type-specfic bindings, you
523 ;; can use commands `bmkp-jump-to-type' and
524 ;; `bmkp-jump-to-type-other-window' (`C-x j :' and `C-x 4 j :').
525 ;; They work for any type, prompting you first for the type, then for
526 ;; a bookmark of that type (only).
528 ;; There are several commands for jumping to a bookmark with tags.
529 ;; The completion candidates can be those bookmarks that have all
530 ;; tags in a given set, some tags in a given set, all tags matching a
531 ;; regexp, or some tags matching a regexp. You are prompted for the
532 ;; set of tags or the regexp to match.
534 ;; These commands all have the prefix key `C-x j t'. The suffix key
535 ;; is `*' for "all" and `+' for "some". The regexp-matching commands
536 ;; precede the suffix key with `%'. For example, `C-x j t % +' jumps
537 ;; to a bookmark you choose that has one or more tags that match the
540 ;; There are some type-specific jump commands for bookmarks with
541 ;; tags. The key sequences for these include a key that indicates
542 ;; the bookmark type, after the `t' indicating tags. For example,
543 ;; commands for jumping to a file or directory bookmark having
544 ;; certain tags use the prefix `C-x j t f' (`f' for file). Similar
545 ;; commands for autofile bookmarks have prefix `C-x j t a' (`a' for
548 ;; For example, `C-x j t f % *' jumps to a file or directory bookmark
549 ;; you choose, where all of its tags match a regexp, and `C-x j t a
550 ;; +' finds a file tagged with at least one of the tags you input.
551 ;; The autofile "jump" commands are really `find-file' commands: they
552 ;; read a file name using `read-file-name' - see (@> "Autofile Bookmarks").
554 ;; Bookmark names are global. File names are not; that is, the
555 ;; non-directory portion is not. Suppose you have two similar
556 ;; directories with some like-named files, perhaps tagged in similar
557 ;; ways. Imagine image files of your vacations organized in
558 ;; different directories by year. It is sometimes useful to narrow
559 ;; your focus to the file bookmarks in one directory.
561 ;; Commands such as `bmkp-file-this-dir-jump' (`C-x j C-f') offer as
562 ;; completion candidates only bookmarks for files and subdirs in the
563 ;; current directory (`default-directory'). For tags, there are
564 ;; equivalent commands. For example, `C-x j t C-f % *' is the same
565 ;; as `C-x j t f % *', but the destinations are limited to files in
566 ;; the current directory. All of the "this-dir" file jump commands
567 ;; are bound to the same keys as the general file jump commands, but
568 ;; with `C-f' instead of `f'.
570 ;; Remember that Bookmark+ collects lots of commands on only a few
571 ;; predefined prefix keys, primarily as a mnemonic device. Nothing
572 ;; requires you to use the long key sequence `C-x j t f % *' to visit
573 ;; a file that has a given set of tags. It is expected that you will
574 ;; bind short key sequences to commands that you use often.
576 ;; The `C-x j' and `C-x 4 j' bindings are global. In addition, in
577 ;; some modes `j' is bound to the corresponding type-specific jump
578 ;; command. For example, in Info mode, `j' is bound to
579 ;; `bmkp-info-jump'. (Dired is an exception here: `J' is used
580 ;; instead of `j', since `j' is already taken for `dired-goto-file'.)
581 ;; These commands are also added to the mode's menu-bar menu.
583 ;; In Dired mode, `C-j' is bound to a special Dired-specific jump
584 ;; command, `bmkp-dired-this-dir-jump', whose destinations all use
585 ;; the current directory (`default-directory'). The aim of `C-j' is
586 ;; not to change directories but to change to a different set of
587 ;; Dired markings, switches, inserted subdirectories, or hidden
588 ;; subdirectories for the same Dired directory.
590 ;; In addition to the predefined bookmark types, which you can use as
591 ;; described above, you can define a "type"-specific jump command for
592 ;; any set of bookmarks. That is, you can use any specific set of
593 ;; bookmarks as the completion candidates for a new jump command.
594 ;; Such a set is really only a pseudo-type: the actual bookmarks can
595 ;; each be of any type.
597 ;; You could use this feature, for example, to define a jump command
598 ;; for the bookmarks that belong to a given project.
600 ;; One way to define such a command is to first mark the bookmarks
601 ;; that you want to be the completion candidates, then use `M-c'
602 ;; (command `bmkp-bmenu-define-jump-marked-command') in the bookmark
605 ;; The `*Bookmark List*' display defines a set of bookmarks, even
606 ;; without markings. So does each bookmark of type bookmark list,
607 ;; that is, a bookmark corresponding to a particular `*Bookmark
608 ;; List*' display state - see
609 ;; (@> "State-Restoring Commands and Bookmarks").
611 ;; You can capture the set of bookmarks corresponding to a `*Bookmark
612 ;; List*' display for use in navigation, that is, as the current
613 ;; "navigation list". Navigation here includes jumping and cycling
614 ;; - see (@> "Cycling, Navigation List, Autonaming").
616 ;; To capture in the navigation list the bookmarks corresponding to
617 ;; either the current `*Bookmark List*' display or a bookmark-list
618 ;; bookmark, use `C-x p B', which is bound to command
619 ;; `bmkp-choose-navlist-from-bookmark-list'. To then jump to a
620 ;; bookmark from such a navigation list, use `C-x j N' or `C-x 4 j N'
621 ;; (`bmkp-jump-in-navlist' or `bmkp-jump-in-navlist-other-window').
623 ;;(@* "Bookmark Tags")
624 ;; ** Bookmark Tags **
626 ;; With Bookmark+ you can bookmark many kinds of Emacs object.
627 ;; Bookmarks record locations - that is their primary purpose. They
628 ;; can also record annotations: general free-text descriptions of
631 ;; Bookmark+ bookmarks can also be tagged, as a way to organize them,
632 ;; which also means as a way to organize the objects that are
635 ;; By "tagging" and "tag" in this context is meant associating
636 ;; keywords or other text with an object, typically in order to
637 ;; classify or characterize it. Tags are metadata about an object.
638 ;; This notion of tagging is sometimes called "delicious" tagging
639 ;; after the Web site www.delicious.com that popularized it
640 ;; (`http://en.wikipedia.org/wiki/Delicious_(website)').
642 ;; Be aware that there is another notion of "tag" associated with
643 ;; Emacs: that involving Emacs tags files, which record the locations
644 ;; of function, variable, etc. definitions in source files. There is
645 ;; no relation between the two notions of "tag".
647 ;; A bookmark tag is a string (or a cons whose car is a string - see
648 ;; (@> "Bookmark Tags Can Have Values")). You can add as many tags
649 ;; as you like to any bookmark, and multiple bookmarks can have the
650 ;; same tag(s). In fact, that's the whole idea behind using them for
653 ;; This feature is unrelated to the fact that bookmarks record
654 ;; locations and are useful for navigating. You can, if you want,
655 ;; use bookmarks to tag files in various ways purely for purposes of
656 ;; organizing them (e.g. into projects), whether or not you ever use
657 ;; the bookmarks as a way to visit them.
659 ;; For example, if you use Dired+ (library `dired+.el'), then you can
660 ;; use `M-b' (`diredp-do-bookmark') in Dired to create an autofile
661 ;; bookmark for each of the marked files in the Dired buffer. Even
662 ;; if you never use those bookmarks for navigating to the files, you
663 ;; can use them with tags to organize the files and thus operate on
666 ;; By default, you create bookmarks without tags and add tags to them
667 ;; later. If you prefer, you can customize option
668 ;; `bmkp-prompt-for-tags-flag' to non-nil so that you are prompted to
669 ;; add tags immediately whenever you set (create) a bookmark. There
670 ;; are also some commands, such as `bmkp-tag-a-file' (`C-x p t + a')
671 ;; and `bmkp-untag-a-file' (`C-x p t - a'), that always prompt for
672 ;; tags to add or remove. (In general, the key `a' is used in key
673 ;; sequences for autofile bookmarks.)
675 ;; When you are prompted to enter a tag, you type some text then hit
676 ;; `RET'. If you want to include a newline character in the tag
677 ;; itself, use `C-q C-j' (`C-j' is the newline character). You can
678 ;; use `C-q' this way to enter any character. If you do use complex
679 ;; strings as tags then you might prefer to simply edit a bookmark's
680 ;; tags in a separate buffer. You can do that using `C-x p t e' (or
681 ;; `T e' in the bookmark-list display).
683 ;; To make tags more useful, Bookmark+ provides *lots* of commands:
684 ;; commands for adding, removing, copying, pasting, and renaming
685 ;; tags; commands for jumping to bookmarks with particular sets of
686 ;; tags; and commands for marking or unmarking (in buffer `*Bookmark
687 ;; List*') bookmarks that are tagged in various ways.
689 ;; Most commands pertaining to tags are by default on prefix key `C-x
690 ;; p t' - use `C-x p t C-h' to see them. In buffer `*Bookmark
691 ;; List*', commands pertaining to tags are on prefix key `T' - use `T
694 ;; When combined with other Bookmark+ commands (e.g. search,
695 ;; query-replace) that apply to the marked bookmarks in the
696 ;; `*Bookmark List*' window, you can really do quite a lot using
697 ;; bookmark tags. Use your imagination!
701 ;; * (@> "Bookmarking the Marked Files in Dired")
702 ;; * (@> "Opening Bookmarks Using Windows File Associations")
703 ;; * (@> "Tag Commands and Keys")
705 ;;(@* "Bookmark Tags Can Have Values")
706 ;; ** Bookmark Tags Can Have Values **
708 ;; Bookmark tags are simply names (strings) when you create them.
709 ;; Nearly all of the predefined operations that use tags use these
710 ;; names: sorting, marking, jumping, and so on. But you can in fact
711 ;; add an associated value to any tag. This means that a tag can act
712 ;; just like an object attribute or property: it can be a name/value
715 ;; To add a value to a tag that has none, or to change the current
716 ;; value of a tag, you use command `bmkp-set-tag-value', which is
717 ;; bound to `T v' in the bookmark list and bound to `C-x p t v'
718 ;; globally. You are prompted for the bookmark, the tag, and the new
721 ;; A tag value can be a number, symbol, string, list, vector, and so
722 ;; on. It can be as complex as you like. It can be any Emacs-Lisp
723 ;; object that has read syntax, that is, that is readable by the Lisp
724 ;; reader. (Everything that is saved as part of a bookmark must be
725 ;; readable; otherwise, your bookmark file could not be read
728 ;; Because tag values can be pretty much anything, you are pretty
729 ;; much on your own when it comes to making use of them. Bookmark+
730 ;; does not provide predefined functions for using tag values. In
731 ;; general, tag values are something you will use with home-grown
732 ;; Lisp code for your own purposes.
734 ;; However, you can easily make some interactive use of tag values
735 ;; with little effort. You can, for example, define a predicate that
736 ;; tests whether a bookmark has a tag value that satisfies some
737 ;; property (e.g. is a number greater than 3.14159265358979), and
738 ;; then you can use command `bmkp-bmenu-mark-bookmarks-satisfying' to
739 ;; mark those bookmarks.
741 ;; Tags that have the prefix "bmkp-" are reserved - do not name your
742 ;; own tags using this prefix.
744 ;; Currently, "bmkp-jump" is the only predefined bookmark tag. You
745 ;; can give this tag a value that is a function - it is called
746 ;; whenever the tagged bookmark is visited. Any Lisp-readable
747 ;; function value is allowed: a symbol or a lambda expression.
749 ;; For example, to display `Hello!' when a bookmark is visited you
752 ;; T v bookmark-jump RET (lambda () (message "Hello!"))
754 ;; The function that is the value of a "bmkp-jump" tag is called just
755 ;; after the the standard hook `bookmark-after-jump-hook' is invoked.
756 ;; You can use this tag to invoke functions that are specific to
757 ;; individual bookmarks; bookmarks can thus have their own, extra
760 ;;(@* "Function, Sequence, and Variable-List Bookmarks")
761 ;; ** Function, Sequence, and Variable-List Bookmarks **
763 ;; Bookmarks are typically thought of only as recorded locations.
764 ;; Invoking a bookmark, called "jumping" to it, traditionally means
765 ;; just visiting its location. Bookmark+ looks at bookmarks in a
766 ;; more general way than that. A bookmark is a shortcut of some
767 ;; kind - nothing more.
769 ;; A given type of bookmark is defined by its handler function, which
770 ;; really could do anything you like. We've already seen the
771 ;; examples of region bookmarks, which restore the active region, and
772 ;; Dired bookmarks, which restore a set of Dired markings, switches,
773 ;; inserted subdirectories, and hidden (sub)directories.
775 ;; A "function bookmark" simply invokes some function - any function.
776 ;; You can, for instance, define a window or frame configuration and
777 ;; record that as a bookmark. Then jump to the bookmark to switch
778 ;; contexts. (You can also bookmark a desktop and jump to that.)
780 ;; Function bookmarks might not seem too interesting, since we have
781 ;; other ways of invoking functions in Emacs. But the other features
782 ;; of Bookmark+ combine with this feature. You can, for instance,
783 ;; tag such bookmarks.
785 ;; And you can combine them, invoking the functions sequentially.
786 ;; This is just a particular case of using a "sequence bookmark",
787 ;; which simply records a sequence of bookmarks. The bookmarks in a
788 ;; sequence can be of any kind, including other sequence bookmarks.
790 ;; Command `bmkp-make-function-bookmark' creates a function bookmark
791 ;; - you give it a function symbol or a lambda expression. Command
792 ;; `bmkp-bmenu-make-sequence-from-marked' creates a sequence from the
793 ;; marked bookmarks in the bookmark list, in their current order.
795 ;; A variable-list bookmark saves and restores the values of a set of
796 ;; variables. Command `bmkp-set-variable-list-bookmark' prompts you
797 ;; for the variables to include in the list and then sets the
798 ;; bookmark. Command `bmkp-jump-variable-list' (`C-x j v') restores
799 ;; the recorded variable values for the bookmark's buffer. You can
800 ;; also create variable-list bookmarks non-interactively, using
801 ;; function `bmkp-create-variable-list-bookmark'.
803 ;; If you use library `wide-n.el', then you can move among multiple
804 ;; restrictions (narrowings) in a buffer. The restrictions are
805 ;; stored in buffer-local variable `wide-n-restrictions'. Command
806 ;; `bmkp-set-restrictions-bookmark' bookmarks this value for the
807 ;; current buffer. Jumping to such a bookmark restores the saved
808 ;; ring/stack of restrictions.
810 ;;(@* "Editing Bookmarks")
811 ;; ** Editing Bookmarks **
813 ;; In vanilla Emacs, you can use `e' in the bookmark list display to
814 ;; edit the annotation associated with a bookmark. And you can use
815 ;; `r' to rename a bookmark. But that is all. There is no easy way
816 ;; to really edit a bookmark.
818 ;; With Bookmark+, in addition to `e' and `r', you can use `E' in the
819 ;; bookmark list, or `C-x p E' anywhere, to edit the bookmark name
820 ;; and the target file name (bookmarked location). You are prompted
821 ;; for the new names.
823 ;; If you use a prefix argument (`C-u E' in the bookmark list or `C-u
824 ;; C-x p E' elsewhere), then you can edit the complete internal
825 ;; bookmark record - the Lisp definition. This is the same internal
826 ;; definition that you see when you use `C-u C-h RET' in the bookmark
829 ;; Use `C-c C-c' when you are done editing the bookmark record, to
830 ;; save your changes. The number of visits and the time last visited
831 ;; for the bookmark are updated automatically (unless you use a
832 ;; prefix argument: `C-u C-c C-c').
834 ;; When you use `C-c C-c', Bookmark+ does a quick check to see if it
835 ;; recognizes the bookmark type as valid. This is not a complete
836 ;; bookmark validity check, but it can help to let you know if you
837 ;; make an editing mistake that renders the bookmark record invalid.
839 ;; In that case, you are asked whether you want to save the changes
840 ;; anyway. Remember that you can use `undo' to reverse particular
841 ;; changes or simply kill the edit buffer to abandon all changes.
843 ;; In a similar way, you can use `T e' in the bookmark list or `C-x p
844 ;; t e' elsewhere, to edit a bookmark's tags.
846 ;;(@* "Bookmark-List Views - Saving and Restoring State")
847 ;; ** Bookmark-List Views - Saving and Restoring State **
849 ;; The bookmark list (buffer `*Bookmark List*') provides a view into
850 ;; the set of bookmarks. You can mark, sort, and hide (filter, omit)
851 ;; bookmarks - see (@> "The Bookmark List (Display)"). The state of
852 ;; the displayed bookmark list can thus change.
854 ;; At different times, and in different contexts, different views can
855 ;; be useful. Bookmark+ lets you save the current state of the
856 ;; displayed list and later restore it. There are a couple of
857 ;; different ways to do this.
860 ;;(@* "Quitting Saves the Bookmark-List State")
861 ;; *** Quitting Saves the Bookmark-List State ***
863 ;; If option `bmkp-bmenu-state-file' is non-nil, which it is by
864 ;; default, then Bookmark+ remembers the last state of the bookmark
865 ;; list when you quit it or you quit Emacs, and it restores that
866 ;; state when you show the list again (which could be in the next
867 ;; Emacs session). You can think of this feature as your "Home" page
868 ;; for bookmarks, giving you a stepping stone to the files and
869 ;; directories you use most.
871 ;; If, for example, when you quit the bookmark list you are showing
872 ;; only bookmarks to Info nodes and UNIX manual pages, sorted in a
873 ;; particular way, and with some of them marked for particular
874 ;; processing, then the next time you open the list the same state is
875 ;; restored: the same set of bookmarks is shown, in the same order,
876 ;; with the same markings.
878 ;; You can turn off this automatic bookmark-list display state
879 ;; saving, if you want, by customizing option `bmkp-bmenu-state-file'
880 ;; to nil. And you can toggle this option at any time, using `M-l'
881 ;; in the bookmark list (command
882 ;; `bmkp-toggle-saving-menu-list-state'). In particular, if you want
883 ;; your next visit to the bookmark list to start out with a
884 ;; previously recorded state instead of the current state, just hit
885 ;; `M-l' before quitting the bookmark list.
888 ;;(@* "State-Restoring Commands and Bookmarks")
889 ;; *** State-Restoring Commands and Bookmarks ***
891 ;; In addition to automatically saving/restoring the final
892 ;; bookmark-list display state, you can save this state at any time,
893 ;; any number of times, for later restoration. This gives you the
894 ;; ability to create multiple persistent views of your bookmarks.
896 ;; There are two ways to do this:
898 ;; * Create a bookmark for the `*Bookmark List*' buffer itself: a
899 ;; bookmark-list bookmark.
901 ;; * Define a command that restores the bookmark-list state.
903 ;; When you use `C-x r m' (`bookmark-set') in buffer `*Bookmark
904 ;; List*' to create a bookmark-list bookmark, the current sort order,
905 ;; filter, regexp pattern, title, and omit list are saved as part of
906 ;; the bookmark. (These concepts are described below - see
907 ;; (@> "Bookmark List (Display)").) Jumping to such a bookmark
908 ;; restores all of these.
910 ;; Alternatively, you can define a command that does the same thing,
911 ;; but without creating another bookmark - use `c'
912 ;; (`bmkp-bmenu-define-command') in the bookmark list to do this.
913 ;; You are prompted for the name of the new command. Use the command
914 ;; anytime (including in another Emacs session) to restore the
917 ;; Define any number of such commands for the views you use. The
918 ;; file for saving the definitions (see option
919 ;; `bmkp-bmenu-commands-file') is never overwritten, so you can also
920 ;; add other code to it manually, if you want. The file is read the
921 ;; first time the bookmark list is displayed in a given Emacs
924 ;; The state that is saved and restored using a bookmark-list
925 ;; bookmark or a command defined using `c' is only a partial state.
926 ;; The current set of markings and some other information are not
927 ;; saved, in order to save disk space and save/restore time.
929 ;; Sometimes, however, you really want to save the entire
930 ;; bookmark-list state, creating a full snapshot. You can use `C'
931 ;; (`bmkp-bmenu-define-full-snapshot-command') to do that. This
932 ;; defines a command that restores the bookmark list completely.
933 ;; That is the same thing that happens automatically (by default)
934 ;; whenever you quit the bookmark list (or Emacs), but defining
935 ;; snapshot commands lets you have multiple saved states and switch
938 ;; Be aware, however, that full-snapshot command definitions can be
939 ;; quite large, since they each contain a copy of the current
940 ;; bookmark list and any accessory lists (hidden and marked bookmarks
943 ;; Whether you use `c' or `C' to define a state-restoring command or
944 ;; you create a bookmark-list bookmark, you can create a sequence
945 ;; bookmark that combines such bookmark-list restoration with
946 ;; activation of other bookmarks. (To include a state-restoring
947 ;; command in a sequence, you need to first create a function
948 ;; bookmark that uses the command, and then include that bookmark in
951 ;;(@* "Bookmarking without Visiting the Target")
952 ;; ** Bookmarking without Visiting the Target **
954 ;; There are several use cases for bookmarking a target without first
957 ;; 1. In an Emacs buffer you come across a reference or a link to a
958 ;; file or a URL. You bookmark the target without bothering to
959 ;; visit it first. You do not really care which position in the
960 ;; file is bookmarked.
962 ;; 2. In Dired, you mark certain files and then bookmark all (each)
963 ;; of them, in one operation.
965 ;; 3. As a special case of #1 and #2, you bookmark a file that you
966 ;; cannot visit in Emacs (in the sense of editing it in a buffer)
967 ;; - for example, a music file. "Jumping" to the bookmark
968 ;; performs an operation appropriate to the file - for example,
971 ;; 4. In a compilation buffer (e.g. `*grep*', `*compile*') or an
972 ;; occur or multi-occur buffer (`*Occur*'), you bookmark one or
973 ;; more of the hits. Such a bookmark takes you to the appropriate
974 ;; position in the target file or buffer.
977 ;;(@* "Bookmarking a File or a URL")
978 ;; *** Bookmarking a File or a URL ***
980 ;; You can use commands `bmkp-file-target-set' and
981 ;; `bmkp-url-target-set', bound by default to `C-x p c f' and `C-x p
982 ;; c u', to bookmark any file or URL. Completion is available, the
983 ;; default file name or URL being determined by the text at point.
984 ;; In addition to the file or URL, you are prompted for the bookmark
985 ;; name. (In general, the keys `f' and `u' are used in key sequences
986 ;; for file and URL bookmarks, respectively.)
989 ;;(@* "Autofile Bookmarks")
990 ;; *** Autofile Bookmarks ***
992 ;; Autofile bookmarking represents a special case of bookmarking a
993 ;; file without visiting it. For an autofile bookmark you need not
994 ;; provide the bookmark name - you specify only the file to bookmark.
995 ;; You can create a new autofile bookmark, or set an existing one,
996 ;; using `bmkp-bookmark-a-file' (aka `bmkp-autofile-set'), which is
997 ;; bound by default to `C-x p c a'. (In general, the key `a' is used
998 ;; in key sequences for autofile bookmarks.)
1000 ;; If user option `bmkp-propertize-bookmark-names-flag' is non-nil,
1001 ;; which it is by default with Emacs 21 and later, then you can have
1002 ;; multiple bookmarks with the same name. This is important for
1003 ;; autofile bookmarks because the bookmark name is only the
1004 ;; non-directory part of the file name. This Bookmark+ feature lets
1005 ;; you have different autofile bookmarks for files of the same name
1006 ;; in different directories.
1008 ;; Because an autofile bookmark name is the same as its
1009 ;; (non-directory) file name, you can define and use file-visiting
1010 ;; commands where the file name is read using `read-file-name' with a
1011 ;; predicate that tests various bookmark fields.
1013 ;; For example, by default (for Emacs 21 or later), you can use `C-x
1014 ;; j a' or `C-x 4 j a' to visit an autofile bookmark. These keys are
1015 ;; bound to `bmkp-find-file' and `bmkp-find-file-other-window',
1016 ;; respectively (which are also known as `bmkp-autofile-jump' and
1017 ;; `bmkp-autofile-jump-other-window').
1019 ;; Similarly, you can use prefix key `C-x j t a' followed by the
1020 ;; usual tags-command suffix keys (e.g. `+', `% *') to visit a file
1021 ;; or directory (that is, jump to an autofile bookmark) that is
1022 ;; tagged in a particular way. See (@> "Tagging Files"). All of the
1023 ;; autofile "jump" commands are really `find-file' commands: they
1024 ;; read a file name using `read-file-name', letting you navigate up
1025 ;; and down the file hierarchy.
1027 ;; In addition to the single autofile bookmark you can create for a
1028 ;; given absolute file location, you can of course create additional
1029 ;; bookmarks to the same file, using different bookmark names. Among
1030 ;; other things, this lets you tag the same file in different ways.
1033 ;;(@* "Bookmarking the Marked Files in Dired")
1034 ;; *** Bookmarking the Marked Files in Dired ***
1036 ;; If you use Dired+ (library `dired+.el'), then you can bookmark all
1037 ;; of the marked files in a Dired buffer at once, as autofiles, even
1038 ;; if you normally do not or cannot visit those files in Emacs.
1039 ;; These keys are available in Dired:
1041 ;; `M-b' - Bookmark each marked file
1042 ;; `C-M-S-b' (aka `C-M-B') - Bookmark each marked file in a
1043 ;; bookmark-file that you specify
1044 ;; `C-M-b' - Bookmark each marked file in a
1045 ;; bookmark-file you specify, and create
1046 ;; a bookmark for that bookmark-file
1048 ;; Each of these commands bookmarks each of the marked files as an
1049 ;; autofile. By default, the bookmark file used for the latter two
1050 ;; commands is in the current directory.
1052 ;; If you use multiple `C-u' as a prefix arg for these commands, then
1053 ;; you can bookmark all of the files in Dired, regardless of
1054 ;; markings, as follows:
1056 ;; `C-u C-u' - Use all files in Dired, except directories
1057 ;; `C-u C-u C-u' - Use all files and dirs, except `.' and `..'
1058 ;; `C-u C-u C-u C-u' - Use all files and all directories
1060 ;; `C-M-b' not only bookmarks each of the marked files, it also
1061 ;; creates a bookmark-file bookmark for that set of bookmarks. See
1062 ;; (@> "Bookmark-File Bookmarks"), below.
1064 ;; You can later "jump" to that bookmark to load its set of
1065 ;; bookmarks. If you use `C-u' when you jump to it, then you switch
1066 ;; bookmark files, so that `C-x r l' displays only the bookmarks
1067 ;; created from the marked files. Without `C-u', jumping to the
1068 ;; bookmark-file bookmark simply loads its bookmarks into the current
1069 ;; set of bookmarks.
1072 ;;(@* "Bookmarking Compilation, Grep, and Occur Hits")
1073 ;; *** Bookmarking Compilation, Grep, and Occur Hits ***
1075 ;; In a similar way, you can bookmark the file or buffer positions of
1076 ;; selected hits in a compilation buffer (including `*grep*') or an
1077 ;; `occur' or `multi-occur' buffer.
1079 ;; `C-c C-b' in such a buffer bookmarks the target of the hit at
1080 ;; point. `C-c C-M-b' bookmarks the target of each hit in the
1083 ;; `C-c C-M-b' in these buffers is thus similar to `M-b' in a Dired
1084 ;; buffer. Unlike Dired, however, there is no way to mark such hits.
1085 ;; Every hit is bookmarked.
1087 ;; Nevertheless, you can get the same effect. Just use `C-x C-q' to
1088 ;; make the buffer writable (e.g. temporarily), and then remove any
1089 ;; hits that you do not want to bookmark. You can remove hits anyway
1090 ;; you like, including by `C-k' and by regexp (`M-x flush-lines' or
1091 ;; `M-x keep-lines').
1093 ;; See also: (@> "Autonamed Bookmarks - Easy Come Easy Go"),
1094 ;; bookmarking occur hits using autonamed bookmarks.
1097 ;;(@* "Bookmarking Files That You Cannot Visit")
1098 ;; *** Bookmarking Files That You Cannot Visit ***
1100 ;; There are lots of files that you use that you never visit, but
1101 ;; that you might like to keep track of or access in other ways
1102 ;; besides opening them in Emacs: music files, image files, whatever.
1104 ;; You can define a new kind of bookmark for any file type you are
1105 ;; interested in, implementing a bookmark handler for it that
1106 ;; performs the appropriate action on it when you "jump" to it. That
1107 ;; action needs to be expressible using an Emacs function, but it
1108 ;; need not have anything to do with visiting the file in Emacs.
1110 ;; When you bookmark a target file that Emacs recognizes as an image
1111 ;; or sound file, an appropriate handler is used automatically.
1113 ;; After you create individual bookmarks for, say, music or image
1114 ;; files, you can use `P B' in the bookmark-list display to show only
1115 ;; those bookmarks, and then use `C-x r m' to bookmark that state of
1116 ;; the bookmark-list.
1118 ;; That bookmark-list bookmark in effect becomes a music playlist or
1119 ;; an image library or slideshow. Jump to it anytime you want to
1120 ;; listen to that set of music pieces or view those images. And you
1121 ;; can use `C-x p B' and then `C-x p next' to cycle among the music
1122 ;; pieces or images (slideshow). (See (@> "Cycling the Navigation List").)
1124 ;; Together with the use of bookmark tags, this gives you a handy way
1125 ;; to organize and access objects of any kind. See (@> "Bookmark Tags").
1127 ;; You use option `bmkp-default-handler-associations' to control
1128 ;; which operation (bookmark handler) to use for which file type.
1129 ;; This is a set of associations (an alist) with key a regexp
1130 ;; matching a file name and with value a Lisp sexp that evaluates to
1131 ;; either a shell command (a string) or an Emacs function (a symbol
1134 ;; The handler for the bookmark created invokes the shell command or
1135 ;; the Emacs function with the file name as argument.
1137 ;; Here is an example option value:
1139 ;; (("\\.ps$" . "gsview32.exe")
1140 ;; ("\\.html?$" . browse-url))
1142 ;; This value creates a bookmark that, when you jump to it, invokes
1143 ;; shell command `gsview32.exe' on the bookmark's target file if it
1144 ;; is PostScript (extension `.ps'), and invokes Emacs Lisp function
1145 ;; `browse-url' on the file if it is HTML (extension `.htm' or
1148 ;; The default value of `bmkp-default-handler-associations' is taken
1149 ;; from the value of option `dired-guess-shell-alist-user' (from
1152 ;; If no matching file association is found in
1153 ;; `bmkp-default-handler-associations', and if option
1154 ;; `bmkp-guess-default-handler-for-file-flag' is non-nil (it is nil
1155 ;; by default), then Bookmark+ will guess a shell command to use in
1156 ;; the handler. It does this by matching the file name against
1157 ;; `dired-guess-shell-alist-default' (also from Dired X). In Emacs
1158 ;; 23+, if it finds no shell command that way then it guesses one
1159 ;; based on mailcap entries.
1162 ;;(@* "Opening Bookmarks Using Windows File Associations")
1163 ;; *** Opening Bookmarks Using Windows File Associations ***
1165 ;; If you use Microsoft Windows there is no need to define new
1166 ;; bookmark types and handlers, if the action you want is the one
1167 ;; that Windows associates with the file. You already have a set of
1168 ;; file/program associations, and Bookmark+ recognizes these as
1169 ;; alternative handlers.
1171 ;; You can thus take advantage of Windows file associations to open
1172 ;; bookmarks for files of all kinds. To do this, you also need
1173 ;; library `w32-browser.el'. In the bookmark list, the following
1174 ;; keys are bound to commands that open bookmarks using the
1175 ;; associated Windows `Open' applications:
1177 ;; `M-RET' - `bmkp-bmenu-w32-open'
1178 ;; `M-mouse-2' - `bmkp-bmenu-w32-open-with-mouse'
1179 ;; `M-o' - `bmkp-bmenu-w32-open-select'
1181 ;; Windows file associations are always available to you, in addition
1182 ;; to any other file associations that you define using
1183 ;; `bmkp-default-handler-associations' (see
1184 ;; (@> "Bookmarking Files That You Cannot Visit")).
1186 ;; You can thus have two different programs associated with the same
1187 ;; kind of file. Your MS Windows file association for PostScript
1188 ;; might, for example, use Adobe Distiller to create a PDF file from
1189 ;; PostScript, while your `bmkp-default-handler-associations'
1190 ;; association for PostScript might use GhostView to display it
1193 ;;(@* "Tagging Files")
1194 ;; ** Tagging Files **
1196 ;; Section (@> "Tags: Sets of Bookmarks") covers bookmark tags, which
1197 ;; are persistent metadata that you define to help you organize
1198 ;; bookmarks into meaningful sets.
1200 ;; Section (@> "Autofile Bookmarks") describes autofile bookmarks,
1201 ;; which, in effect, let you treat files generally as if they were
1202 ;; bookmarks. You can choose a file to visit or act on by its name
1203 ;; and location, but also by its bookmark metadata.
1205 ;; In particular, you can tag a file - that is, specify tags for its
1206 ;; associated autofile bookmark. And you can then visit a file that
1207 ;; has a given set of tags. Bookmark+ provides file commands that
1208 ;; automatically create and manipulate autofile bookmarks, that is,
1209 ;; bookmarks that have the same name as the files they tag.
1211 ;; Command `bmkp-tag-a-file' (aka `bmkp-autofile-add-tags'), bound by
1212 ;; default to `C-x p t + a', prompts you for a set of tags and a file
1213 ;; location, and creates or sets the corresponding autofile bookmark.
1214 ;; Command `bmkp-untag-a-file' (aka `bmkp-autofile-remove-tags'),
1215 ;; bound by default to `C-x p t - a', similarly lets you remove
1216 ;; specified tags from a file.
1218 ;; If you also use library Icicles, then you can act on multiple
1219 ;; files during the same command (a "multi-command"). You can thus
1220 ;; all at once tag a set of files the same way, or act on a set of
1221 ;; files that are tagged similarly.
1223 ;; If you also use library Dired+ (`dired+.el') then you can use
1224 ;; `C-+' to add tags to the marked files and `C--' to remove tags
1225 ;; from them. You can use `C-M-+' and `C-M--' to do the same thing
1226 ;; for the current file. You can also use items from the Dired menus
1227 ;; to do these things.
1229 ;; Bookmark+ provides two kinds of command for visiting files
1230 ;; associated with bookmarks that have tags.
1232 ;; The first kind uses bookmarks directly: you choose a bookmark
1233 ;; name, not a file name, but the candidates are only file and
1234 ;; directory bookmarks. These commands have the prefix `bmkp-file-'.
1236 ;; As a special case, commands with the prefix `bmkp-file-this-dir-'
1237 ;; limit the choices to bookmarks for files and subdirectories of the
1238 ;; current directory. By default, the commands across all
1239 ;; directories are on prefix key `C-x 4 j t f' and those for the
1240 ;; current directory only are on prefix key `C-x j t C-f'. See
1241 ;; (@> "Different Types of Jump Commands") for more about these
1244 ;; The second kind of command is for visiting tagged files, that is,
1245 ;; autofile bookmarks. These commands are available only for Emacs
1246 ;; 21 and later (because they use `read-file-name' with a PREDICATE
1247 ;; argument, not available for Emacs 20). The candidates are file
1248 ;; names, not bookmark names. These commands have the prefix
1249 ;; `bmkp-find-file-', and by default they are on the prefix key `C-x
1250 ;; j t a'. (In general, the keys `f' and `a' are used in key
1251 ;; sequences for file and autofile bookmarks, respectively.)
1255 ;; `C-x j t f % +' is `bmkp-file-some-tags-regexp-jump'
1256 ;; `C-x j t C-f % +' is `bmkp-file-this-dir-some-tags-regexp-jump'
1257 ;; `C-x j t a % +' is `bmkp-find-file-some-tags-regexp'
1259 ;; * The first of these visits any file bookmark that has at least
1260 ;; one tag among the tags you specify, and you choose among
1261 ;; bookmark names. The files can be in any directories.
1263 ;; * The second is similar to the first, but only bookmarks for files
1264 ;; in the current directory are candidates.
1266 ;; * The third is similar regarding tags, but it uses
1267 ;; `read-file-name', so you can browse among all files, up and down
1268 ;; the file hierarchy. The candidates are file names, not bookmark
1271 ;; If you use Icicles, there are similar sets of commands, but they
1272 ;; all let you act on multiple files at the same time
1273 ;; (multi-commands). For example, you can delete (or byte-compile
1274 ;; or...) a set of files according to their tags.
1276 ;; Remember that you can create multiple bookmarks for the same file,
1277 ;; providing them with different sets of tags. (Only one of the
1278 ;; bookmarks is the autofile bookmark.)
1280 ;; You can also use multiple bookmark files (the files that record
1281 ;; bookmarks). Different projects can thus have different tags for
1282 ;; the same sets of files, even using just autofile bookmarks. See
1283 ;; (@> "Using Multiple Bookmark Files").
1285 ;; A file bookmark can have any number of tags, and multiple file
1286 ;; bookmarks can have the same tag. You can sort, show/hide, or mark
1287 ;; files based on their tags.
1289 ;;(@* "Using Multiple Bookmark Files")
1290 ;; ** Using Multiple Bookmark Files **
1292 ;; Bookmark-list views (see
1293 ;; (@> "Bookmark-List Views - Saving and Restoring State")) provide
1294 ;; one way to switch among various sets of bookmarks that you use.
1295 ;; But that feature affects only the bookmarks that you see displayed
1296 ;; in buffer `*Bookmark List*', not the actual set of available
1299 ;; The bookmarks available to you are defined in a bookmark file. By
1300 ;; default, they are stored in the file named by option
1301 ;; `bookmark-default-file' (`~/.emacs.bmk', by default). You do not
1302 ;; need to load or save this file manually; Emacs does that for you
1305 ;; But you can also have extra, alternative bookmark files if you
1306 ;; want, and at any time you can change the bookmark file that is
1307 ;; current. To do that, use `C-x p L' (uppercase `L'), which is
1308 ;; bound to command `bmkp-switch-bookmark-file'.
1310 ;; Having multiple bookmark files gives you an added degree of
1311 ;; flexibility. You can see which file is current at any time by
1312 ;; using `?' or `C-h m' in the buffer `*Bookmark List*' (or anywhere
1313 ;; else using `M-x bmkp-bmenu-mode-status-help').
1315 ;; When you switch to another bookmark file, the default file to
1316 ;; switch to is the last bookmark file you used (in the same
1317 ;; session). So it is trivial to toggle back and forth between two
1318 ;; bookmark files: just hit `RET' to accept the default.
1320 ;; When bookmarks are saved automatically, or when you save them
1321 ;; using `bookmark-save' (`S' in the bookmark list or `C-x p s'
1322 ;; globally) and you don't use a prefix argument, they are saved in
1323 ;; the current bookmark file.
1325 ;; You can turn off the automatic saving of the current bookmark
1326 ;; file, by customizing option `bookmark-save-flag' to nil. And you
1327 ;; can toggle this option at any time, using `M-~' in the bookmark
1328 ;; list (command `bmkp-toggle-saving-bookmark-file').
1330 ;; Besides using multiple bookmark files as *alternatives*, you can
1331 ;; combine them, using them as component bookmark subsets (like
1332 ;; modules). To do that, use command `C-x p l' (lowercase `l'),
1333 ;; which is bound to `bookmark-load', and do not use a prefix
1334 ;; argument. (Using a prefix argument with `C-x p l' is the same as
1335 ;; using `C-x p L': it switches bookmark files.) Here too the
1336 ;; default is the name of the last bookmark file that you used.
1338 ;; To create additional bookmark files, to use either as alternatives
1339 ;; or as components, you can either copy an existing bookmark file or
1340 ;; use `bmkp-empty-file' (`C-x p 0') to create a new, empty bookmark
1341 ;; file. If you use `C-x p 0' with an existing bookmark file, then
1342 ;; its bookmarks are all deleted - it is emptied.
1344 ;; Instead of simply copying a bookmark file, you can use
1345 ;; `bookmark-save' with a prefix argument, or use `bookmark-write'
1346 ;; (bound to `C-x p w'), to save the currently defined bookmarks to a
1347 ;; different bookmark file.
1349 ;; However a bookmark file was created, you can switch to it and then
1350 ;; add or delete bookmarks selectively, to change its content.
1351 ;; Remember that you can delete bookmarks from the current set using
1352 ;; command `bookmark-delete' (`C-x p d') or, in the bookmark list,
1353 ;; using `d' plus `x' or marking then `D'.
1356 ;;(@* "Bookmark-File Bookmarks")
1357 ;; *** Bookmark-File Bookmarks ***
1359 ;; A bookmark file is an excellent, persistent way to represent a set
1360 ;; of bookmarks. In particular, it can represent a project or a
1361 ;; project component. Switch among bookmark files to access
1362 ;; different projects. Load project components as you need them.
1364 ;; You can load a bookmark file using `C-x p L' (switch) or `C-x p l'
1365 ;; (accumulate). As a convenience, you can also load a bookmark file
1366 ;; by jumping to a bookmark-file bookmark.
1368 ;; You use command `bmkp-set-bookmark-file-bookmark', bound to `C-x p
1369 ;; x', to create a bookmark-file bookmark. Jumping to such a
1370 ;; bookmark just loads the bookmark file that it records. With `C-u'
1371 ;; (e.g. `C-u C-x p j project-foo'), jumping switches bookmark files.
1372 ;; Without `C-u' it accumulates the loaded bookmarks.
1374 ;; A bookmark-file bookmark is not only an added convenience. You
1375 ;; can also use it in combination with other Bookmark+ features, such
1378 ;; As a shortcut, in Dired (if you use library Dired+), `C-M-b'
1379 ;; creates a bookmark-file bookmark. The bookmark file that it
1380 ;; records contains autofile bookmarks to each of the files that was
1381 ;; marked in Dired at the time it was created. Jumping to that
1382 ;; bookmark-file bookmark makes those (marked) files available as
1383 ;; bookmarks. See also
1384 ;; (@> "Use Dired to Bookmark Files without Visiting Them").
1386 ;; Note that the bookmark file in which a bookmark-file bookmark is
1387 ;; recorded is not the same as the bookmark file recorded in that
1390 ;; For example, when you use `C-M-b' in Dired, the bookmark-file for
1391 ;; the marked files is, by default, file `.emacs.bmk' in the Dired
1392 ;; directory. So if you are in directory `/foo/bar' the default
1393 ;; bookmark file for the marked files is `/foo/bar/.emacs.bmk'. But
1394 ;; the new bookmark-file bookmark created is recorded in the current
1395 ;; bookmark file, whatever that might be (e.g. `~/.emacs.bmk').
1397 ;;(@* "The Bookmark List (Display)")
1398 ;; ** The Bookmark List (Display) **
1400 ;; Bookmark+ enhances the bookmark list (aka the bookmark "menu
1401 ;; list", a misnomer) that is displayed in buffer `*Bookmark List*'
1402 ;; when you use `C-x r l' (command `bookmark-bmenu-list').
1404 ;; Bookmarks are highlighted to indicate their type. You can mark and
1405 ;; unmark bookmarks, show or hide bookmarks of particular types, and
1406 ;; more. Bookmarks that have tags are marked with a `t'. Bookmarks
1407 ;; that have an annotation are marked with an `a' (not with a `*' as
1408 ;; in vanilla `bookmark.el'). Bookmarks that have bookmark-highlight
1409 ;; override settings (see (@> "Defining How to Highlight")) are
1410 ;; marked with a one-character pink background.
1412 ;; Use `?' or `C-h m' in buffer `*Bookmark List*' for more
1413 ;; information about the bookmark list, including the following:
1415 ;; * The current status of sorting, filtering, and marking.
1417 ;; * A legend for the faces used for different bookmark types.
1420 ;;(@* "Tag Commands and Keys")
1421 ;; *** Tag Commands and Keys ***
1423 ;; There are lots of tag-related bookmark commands, and most are
1424 ;; bound to keys in buffer `*Bookmark List*' as well as to other keys
1425 ;; outside it. How can you keep the commands straight or remember
1428 ;; In the bookmark list display, tags-command keys begin with prefix
1429 ;; key `T'. Elsewhere, they begin with prefix key `C-x p t' (or `C-x
1430 ;; j t', for jump commands - see (@> "Different Types of Jump Commands")).
1432 ;; `C-h m' (or `?') is your friend, of course. Likewise `T C-h' and
1433 ;; `C-x p t C-h'. Beyond that, the tag-related keys that are more
1434 ;; than two keystrokes are organized as follows:
1436 ;; They all have the prefix key `T'.
1440 ;; `>' stands for the marked bookmarks
1441 ;; `*' means AND (set intersection; all)
1442 ;; `+' means OR (set union; some/any)
1443 ;; `~' means NOT (set complement)
1445 ;; The key `T m *', for instance, marks (`m') the bookmarks that are
1446 ;; tagged with all (`*' = AND) of a given set of tags. It prompts you
1447 ;; for one or more tags that the bookmarks must have, and it marks
1448 ;; all bookmarks that have all of the tags you enter.
1450 ;; The key `T u ~ +' unmarks (`u') the bookmarks that do not (`~')
1451 ;; have any (`+' = OR) of the tags you specify. And so on.
1453 ;; The marking and unmarking commands for tags compare the tags a
1454 ;; bookmark has with tags that you enter. Any bookmarks that have no
1455 ;; tags are ignored - they are neither marked nor unmarked by these
1458 ;; `+' and `-' can also mean add and remove tags, respectively, and
1459 ;; `>' stands for the marked bookmarks. So `T > +' adds (`+') one or
1460 ;; more tags to each of the marked (`>') bookmarks.
1462 ;; In general, the tag-related commands let you enter a set of tags,
1463 ;; one at a time. Thus, instead of having a command that adds a
1464 ;; single tag to the current bookmark, you have a command that adds
1465 ;; any number of tags to it. To add just a single tag, hit `RET'
1466 ;; twice: once to enter the tag, and once again to indicate that it
1467 ;; is the last (i.e., the only) one.
1469 ;; If you just hit `RET' immediately, specifying an empty set of
1470 ;; tags, then each of the commands does something appropriate. For
1471 ;; `T m *', for instance, an empty list of tags means to mark (only)
1472 ;; the bookmarks that have any tags at all.
1474 ;; Finally, for the marking/unmarking tags commands, a prefix
1475 ;; argument flips the sense of the command, in this way:
1477 ;; "some are" -> "some are NOT", i.e., "not all are" (and vice versa)
1478 ;; "all are" -> "all are NOT", i.e., "none are" (and vice versa)
1482 ;; C-u T m * = T m ~ + (all are NOT = not some are)
1483 ;; C-u T m ~ + = T m * (not some are NOT = all are)
1484 ;; C-u T m + = T m ~ * (some are NOT = not all are)
1485 ;; C-u T m ~ * = T m + (not all are NOT = some are)
1487 ;; You'll figure it out ;-).
1489 ;; Other important keys pertaining to tags (the keys in parentheses
1490 ;; work in any buffer, not just buffer `*Bookmark List*'):
1492 ;; * `C-h RET' (`C-x p ?') shows you the tags that belong to a
1493 ;; bookmark. With a prefix argument it shows you the full internal
1494 ;; form of the tags, that is, the name+value pairs.
1496 ;; * `T e' (`C-x p t e') lets you edit a bookmark's tags.
1498 ;; * `T l' (`C-x p t l') lists all tags currently known to Emacs
1499 ;; (across all bookmarks).
1501 ;; * `T +' (`C-x p t + b') adds some tags to a bookmark.
1502 ;; `T -' (`C-x p t - b') removes some tags from a bookmark.
1503 ;; `T 0' (`C-x p t 0) removes all tags from a bookmark.
1504 ;; `T d' (`C-x p t d) removes a set of tags from all bookmarks.
1506 ;; In the bookmark list display you can also sort bookmarks according
1507 ;; to how they are tagged, even in complex ways. See
1508 ;; (@> "Sorting Bookmarks").
1511 ;;(@* "Tags: Sets of Bookmarks")
1512 ;; *** Tags: Sets of Bookmarks ***
1514 ;; The best way to think about tags is as names of sets. All
1515 ;; bookmarks tagged `blue' constitute the bookmark set named `blue'.
1517 ;; The bookmarks visible in the bookmark list at any time also
1518 ;; constitute an unnamed set. Likewise, the marked bookmarks and the
1519 ;; unmarked bookmarks are unnamed sets. Bookmark+ is all about
1520 ;; helping you act on sets of Emacs objects. Bookmarks are named,
1521 ;; persistent pointers to objects such as files and file sets.
1522 ;; Bookmark tags are named, persistent sets of bookmarks (and hence
1523 ;; of their target objects).
1525 ;; The marking commands make it easy to combine sets as unions or
1526 ;; intersections. And you can give the result a name for quick
1527 ;; access later, just by adding a new tag. in other words, do the
1528 ;; set-definition work only once, and name the result.
1530 ;; How would you tag as `Java IDE Projects' the bookmarks that are
1531 ;; already tagged both `Java' and `ide'?
1533 ;; 1. `T m * Java RET ide RET RET', to mark them.
1534 ;; 2. `T > + Java IDE Projects RET RET, to tag them.
1536 ;; How would you sort your bookmarks, to show all those tagged both
1537 ;; `blue' and `moon' first?
1539 ;; 1. `T m * blue RET moon RET RET', to mark them.
1540 ;; 2. `s >' to sort the marked bookmarks first
1541 ;; (see (@> "Sorting Bookmarks"), below).
1543 ;; If you wanted to show only the marked bookmarks, instead of
1544 ;; sorting to put them first in the list, you would use `>'
1545 ;; instead of `s >'.
1547 ;; How would you query-replace the set of files that are tagged with
1548 ;; any of the tags `alpha', `beta', and `gamma', but are not tagged
1549 ;; `blue' or `moon'?
1551 ;; 1. `F S', to show only the file bookmarks.
1552 ;; 2. `T m + alpha RET beta RET gamma RET RET', to mark the
1553 ;; bookmarks that have at least one of those tags.
1554 ;; 3. `T u + blue RET moon RET RET', to unmark those that are
1555 ;; tagged `blue' or `moon'.
1556 ;; 4. `M-q' to query-replace the marked files.
1558 ;; If that were a set of files that you used often, then you would
1559 ;; name the set by giving the files a new tag.
1561 ;; The point is that bookmarks, and bookmark tags in particular, let
1562 ;; you define and manipulate sets of Emacs objects. It doesn't
1563 ;; matter how you define such a set: regexp matching (marking,
1564 ;; filtering), by object type, by tag combinations... Sets need not
1565 ;; be named to act on them, but you can provide them with persistent
1566 ;; names (tags) to avoid redefining them over and over. Manipulation
1567 ;; of bookmarked objects includes visiting, searching, and
1568 ;; query-replacing. And you can define your own bookmark types
1569 ;; (using bookmark handlers) and associated manipulations.
1572 ;;(@* "Open Dired for the Marked File Bookmarks")
1573 ;; *** Open Dired for the Marked File Bookmarks ***
1575 ;; You've seen that the bookmark list has many features that are
1576 ;; similar to Dired features. But Dired is specialized for files and
1577 ;; directories, and it has many more features for manipulating them.
1578 ;; The bookmark list is not intended to replace Dired.
1580 ;; You can, however, use the bookmark list to take advantage of
1581 ;; arbitrary Dired features for file and directory bookmarks.
1582 ;; Command `bmkp-bmenu-dired-marked' (`M-d >') weds Bookmark+'s
1583 ;; set-defining and set-manipulating features (tagging, marking,
1584 ;; filtering etc.) to Dired's file-manipulating features.
1586 ;; `M-d >' opens a Dired buffer that is specialized for just the
1587 ;; files and directories whose bookmarks are marked in the bookmark
1588 ;; list. (Other marked bookmarks are ignored by the command.) The
1589 ;; files and directories can be located anywhere; they need not be in
1590 ;; the same directory. They are listed in Dired using absolute file
1593 ;; (In Emacs versions prior to release 23.2, only local files and
1594 ;; directories can be handled, due to Emacs bug #5478. In such
1595 ;; versions, remote-file bookmarks are ignored by `M-d >'.)
1597 ;; This Bookmark+ feature makes sets of files and directories
1598 ;; immediately amenable to all of the operations provided by Dired.
1600 ;; It is particularly useful in conjunction with tags. Use bookmark
1601 ;; tags and marks to define a possibly complex set of file and
1602 ;; directory bookmarks. Then hit `M-d >' to list them in a Dired
1603 ;; buffer. Then use any Dired commands you want to act on any of
1606 ;; For example, to compress bookmarked files that are tagged with
1607 ;; both `blue' and `moon':
1609 ;; 1. Mark them using `T m * blue RET moon RET RET'.
1610 ;; 2. Open Dired for them using `M-d >'.
1611 ;; 3. Mark them in Dired, then compress them using `Z'.
1613 ;; Since tags are persistent, Bookmark+ gives you a good way to
1614 ;; define an arbitrary set of files as a project and then open them
1615 ;; in Dired at any time to operate on them.
1617 ;; If you use Dired+ (library `dired+.el'), then a similar feature is
1618 ;; available for the marked files and directories: You can use
1619 ;; `C-M-*' in Dired to open a separate Dired buffer for them only.
1620 ;; You can of course then bookmark that resulting Dired buffer, if
1623 ;; If you use Icicles, then whenever you use a command that reads a
1624 ;; file (or directory) name, you can use `M-|' during file-name
1625 ;; completion to open Dired on the currently matching set of file
1626 ;; names. That is, this is the same kind of special Dired buffer
1627 ;; that is provided for file and directory bookmarks by `M-d >' in
1628 ;; the bookmark list.
1631 ;;(@* "Marking and Unmarking Bookmarks")
1632 ;; *** Marking and Unmarking Bookmarks ***
1634 ;; Bookmark+ enhances the marking and unmarking of bookmarks in the
1635 ;; bookmark list in several ways. These enhancements are similar to
1636 ;; features offered by Dired and Dired-X. You can use:
1638 ;; * `% m' to mark the bookmarks that match a regexp. The entire
1639 ;; line in the bookmark list is checked for a match, that is, both
1640 ;; the bookmark name and the file name, if shown.
1642 ;; * `M-DEL' (or `U') to unmark all bookmarks, or all that are marked
1643 ;; `>', or all that are flagged `D' for deletion.
1645 ;; * `t' to toggle (swap) the marked and unmarked bookmarks: those
1646 ;; that are marked become unmarked, and vice versa.
1648 ;; * `>' to show only the marked bookmarks or `<' to show only the
1649 ;; unmarked bookmarks. Repeat to show them all again.
1651 ;; * `F M', `I M' etc. to mark only the file bookmarks, Info
1652 ;; bookmarks etc. (The first key here is the same as the
1653 ;; corresponding filter key, e.g. `F' for files - see next topic.)
1656 ;;(@* "Filtering Bookmarks (Hiding and Showing)")
1657 ;; *** Filtering Bookmarks (Hiding and Showing) ***
1659 ;; You can hide and show different sets of bookmarks in the bookmark
1660 ;; list. There are commands to show only bookmarks of a particular
1661 ;; type - e.g. `I S' to show only Info bookmarks. These are, in
1662 ;; effect, shortcuts for first marking those bookmarks and then
1663 ;; showing only the marked bookmarks (and then unmarking). For
1664 ;; example, `F S' is a shortcut for `F M >' (and then `U RET').
1666 ;; You can also filter to show only the bookmarks that match a given
1667 ;; regexp. There are two ways to do this:
1669 ;; * Use `P B' (for "pattern", "bookmark") and type a regexp. The
1670 ;; bookmarks are filtered incrementally, as you type. Only the
1671 ;; bookmark name is matched (not the file name). Hit any
1672 ;; non-inserting key, such as `RET', to finish defining the
1675 ;; Similarly, hit `P F' for bookmarks whose file names match a
1676 ;; regexp, `P A' for bookmarks whose annotations match a regexp,
1677 ;; and `P T' for bookmarks with one or more tags that match a
1678 ;; regexp. See (@> "Bookmark Tags"), above, for information about
1681 ;; * Just as in Dired, use `% m' to mark the bookmarks that match a
1682 ;; regexp. Then use `>' to show only the marked bookmarks. See
1683 ;; (@> "Marking and Unmarking Bookmarks"), above.
1685 ;; This method has the advantage that you can show the complement,
1686 ;; the bookmarks that do *not* match the regexp, by using `<'
1687 ;; instead of `>'. It also has the advantage that matching checks
1688 ;; the combination of bookmark name and file name (use `M-t' to
1689 ;; toggle showing file names).
1692 ;;(@* "Only Visible Bookmarks Are Affected")
1693 ;; *** Only Visible Bookmarks Are Affected ***
1695 ;; Commands that operate on the current bookmark or on the marked or
1696 ;; the unmarked bookmarks act only on bookmarks that are displayed
1697 ;; (not hidden). This includes the commands that mark or unmark
1698 ;; bookmarks. This means that you can easily define any given set of
1703 ;; Use `F S' to show only bookmarks associated with files.
1704 ;; Use `% m' to mark those that match a particular regexp.
1705 ;; Use `R S' to show only bookmarks that have regions.
1706 ;; Use `m' to mark some of those region bookmarks individually.
1707 ;; Use `.' to show all bookmarks.
1708 ;; Use `t' to swap marked and unmarked (so unmarked are now marked)
1709 ;; Use `D' to delete all of the marked bookmarks (after confirming)
1711 ;; Together, steps 1-7 delete all file bookmarks that match the
1712 ;; regexp and all region bookmarks that you selectively marked.
1715 ;;(@* "Omitting Bookmarks from Display")
1716 ;; *** Omitting Bookmarks from Display ***
1718 ;; In sections (@> "Marking and Unmarking Bookmarks") and
1719 ;; (@> "Filtering Bookmarks (Hiding and Showing)") you learned how
1720 ;; to hide and show bookmarks in the bookmark list. This section is
1721 ;; about a different kind of hiding, called "omitting".
1723 ;; Omitted bookmarks are not shown in the bookmark list, no matter
1724 ;; what filtering is used. The only way to show omitted bookmarks is
1725 ;; to show all of them and only them, using `O S', which is bound to
1726 ;; command `bmkp-bmenu-show-only-omitted'.
1728 ;; Omitted bookmarks are still available even if they are not shown,
1729 ;; and you can still jump to them (e.g. using `C-x r b'). You just
1730 ;; don't see them in the bookmark list. And that's the reason for
1731 ;; this feature: to hide those bookmarks that you don't care to see.
1733 ;; One use for this feature is to hide the component bookmarks that
1734 ;; make up a sequence bookmark (see
1735 ;; (@> "Function, Sequence, and Variable-List Bookmarks")). The
1736 ;; default behavior when you create a sequence bookmark is in fact to
1737 ;; omit its component bookmarks from the displayed list.
1739 ;; You can omit any bookmarks by marking them and then using `O >'
1740 ;; (`bmkp-bmenu-omit/unomit-marked'). If you are looking at the
1741 ;; omitted bookmarks (after using `O S'), then `O >' un-omits the
1742 ;; bookmarks marked there. Think of two complementary spaces: the
1743 ;; normal bookmark list and the omitted bookmark list. When you use
1744 ;; `O >', the marked bookmarks that are currently shown are moved to
1745 ;; the opposite space.
1747 ;; You can un-omit all of the omitted bookmarks at once, using `O U'
1748 ;; (`bmkp-unomit-all'). You can also call this command from outside
1749 ;; the bookmark-list display.
1752 ;;(@* "Sorting Bookmarks")
1753 ;; *** Sorting Bookmarks ***
1755 ;; Filtering hides certain kinds of bookmarks. Sometimes, you want
1756 ;; to see bookmarks of various kinds, but you want them to be grouped
1757 ;; or sorted in different ways, for easy recognition, comparison, and
1760 ;; Bookmarks shown in the bookmark list are sorted using the current
1761 ;; value of option `bmkp-sort-comparer'. (If that is nil, they are
1762 ;; unsorted, which means they appear in reverse chronological order
1763 ;; of their creation.)
1765 ;; You can use `s s'... (repeat hitting the `s' key) to cycle among
1766 ;; the various sort orders possible, updating the display
1767 ;; accordingly. By default, you cycle among all available sort
1768 ;; orders, but you can shorten the cycling list by customizing option
1769 ;; `bmkp-sort-orders-for-cycling-alist'.
1771 ;; You can also change directly to one of the main sort orders
1772 ;; (without cycling) using `s n', `s f n', etc. - use `C-h m' or `?'
1775 ;; You can reverse the current sort direction (ascending/descending)
1776 ;; using `s r'. Also, repeating any of the main sort-order commands
1777 ;; (e.g. `s n') cycles among that order, the reverse, and unsorted.
1779 ;; For a complex sort, which involves composing several sorting
1780 ;; conditions, you can also use `s C-r' to reverse the order of
1781 ;; bookmark sorting groups or the order within each group (depending
1782 ;; on whether `s r' is also used). Be aware that this can be a bit
1783 ;; unintuitive. If it does not do what you expect or want, or if it
1784 ;; confuses you, then don't use it ;-). (`s C-r' has no noticeable
1785 ;; effect on simple sorting.)
1787 ;; Remember that you can combine sorting with filtering different
1788 ;; sets of bookmarks - bookmarks of different kinds (e.g. Info) or
1789 ;; bookmarks that are marked or unmarked.
1791 ;; Finally, you can easily define your own sorting commands and sort
1792 ;; orders. See macro `bmkp-define-sort-command' and the
1793 ;; documentation for option `bmkp-sort-comparer'. (Bookmark+ uses
1794 ;; option `bmkp-sort-comparer'; it *ignores* vanilla Emacs option
1795 ;; `bookmark-sort-flag'.)
1797 ;; Of particular note is that you can interactively define commands
1798 ;; that sort by a given list of tags - you use keys `T s' (command
1799 ;; `bmkp-define-tags-sort-command') to do that. You are prompted for
1800 ;; the tags to sort by. Bookmarks are sorted first according to
1801 ;; whether they are tagged with the first tag, then the second tag,
1802 ;; and so on. Otherwise, sorting is by bookmark name.
1804 ;; The tags you specify are used, in order, in the name of the new
1805 ;; command. For example, if you enter tags `alpha', `beta', and
1806 ;; `gamma', in that order, then the sorting command created is
1807 ;; `bmkp-bmenu-sort-alpha-beta-gamma'. The new command is saved in
1808 ;; your bookmark commands file (`bmkp-bmenu-commands-file').
1810 ;; Note that because you can add a new tag to all bookmarks that have
1811 ;; some given set of tags, you can use that single (new) tag to
1812 ;; represent the entire tag set. Sorting by that tag is then the
1813 ;; same as sorting by the tag set. You can of course use overlapping
1814 ;; sets in the composite sort command. You can, for example, sort
1815 ;; first according to tag `tag1', which represents the set of tags
1816 ;; `alpha', `beta', `gamma', `delta', and then sort according to tag
1817 ;; `tag2', which represents the set of tags `beta', `delta'.
1819 ;; See also (@> "Use Bookmark+ with Icicles") - the same technique is
1820 ;; used in Icicles for sorting bookmarks as completion candidates.
1822 ;;(@* "Bookmarks for Specific Files or Buffers")
1823 ;; ** Bookmarks for Specific Files or Buffers **
1825 ;; A bookmark typically records a position or a region in a file or
1826 ;; buffer. Sometimes you are interested in accessing or examining
1827 ;; only the bookmarks for particular files or buffers. For example,
1828 ;; you might want to navigate among the bookmarks for the current
1829 ;; buffer. Or you might want to search the regions recorded in the
1830 ;; bookmarks for a particular file.
1832 ;; For a bookmark, the recorded file and buffer name differ in that
1833 ;; the file name is absolute. Bookmarks for buffer `foo.el' include
1834 ;; all files named `foo.el', whereas bookmarks for file
1835 ;; `/project1/lisp/foo.el' include only the files in that one
1838 ;; Bookmark+ provides some commands to handle these use cases. The
1839 ;; keys bound to these commands use `f' for file and `b' for buffer.
1840 ;; In the bookmark-list display, the following keys affect the
1841 ;; bookmarks for a particular file or buffer whose name you provide
1842 ;; (with completion).
1844 ;; * `= f M' and `= b M' - mark
1845 ;; * `= f S' and `= b S' - show (only)
1847 ;; For navigation, the following keys jump to bookmarks for
1848 ;; particular files or buffers. (Use `C-x 4 j' for other-window.)
1850 ;; * `C-x j .' - current buffer
1851 ;; * `C-x j = f' and `C-x j = b' - specified file(s) or buffer(s)
1853 ;; For the `=' keys you are prompted for one or more file names or
1856 ;; Finally, because the bookmarks in the current buffer can be of
1857 ;; particular interest, `C-x p .' opens the bookmark-list display for
1858 ;; only those bookmarks.
1860 ;;(@* "Cycling, Navigation List, Autonaming")
1861 ;; ** "Cycling, Navigation List, Autonaming" **
1863 ;; Using completion to jump to a bookmark is handy. It lets you
1864 ;; choose a bookmark by its name and gives you direct ("random")
1867 ;; Sometimes, however, you don't much care what a bookmark is named,
1868 ;; and you want to cycle quickly among relatively few, related
1869 ;; bookmarks. Obviously, the smaller the number of bookmarks in the
1870 ;; set, the more convenient cycling is - with many bookmarks cycling
1871 ;; can become tedious.
1873 ;; An analogy: If your TV has lots of channels, then the channel
1874 ;; up/down buttons on the remote control are not so useful: 32, 33,
1875 ;; 34, ..., 79! Unless the channel you want happens to be near the
1876 ;; current channel, cycling around a huge ring of channels is not the
1877 ;; way to go. And just because your TV receives lots of channels
1878 ;; does not mean that you watch them all or that you are equally
1879 ;; interested in them all.
1881 ;; Some TV remote controls have a feature that mitigates this
1882 ;; problem. You can define a ring of favorite channels, and there
1883 ;; are two additional buttons that let you cycle forward and backward
1884 ;; around the ring, skipping the channels in between. The number of
1885 ;; favorites is relatively small, so cycling is not tedious. More
1886 ;; importantly, all of the channels in the ring are ones you are
1889 ;; Extend this idea to allow for assigning different sets of channels
1890 ;; to the favorites ring at different times: choose the ring you want
1891 ;; at any time: sports, music, films, science, art, history, and so
1892 ;; on. Add the possibility of sorting those sets in various ways, to
1893 ;; further facilitate cycling, and you arrive at the idea behind the
1894 ;; Bookmark+ navigation list.
1896 ;; Another analogy is a music playlist. You can use Bookmark+ as a
1897 ;; simple music player by bookmarking music files. Similarly, you
1898 ;; can use Bookmark+ to create slideshows by bookmarking image files.
1899 ;; Cycle the navigation list to move through the slide show.
1901 ;; If you use MS Windows, you can take advantage of your existing
1902 ;; file associations to open your bookmarks using the appropriate
1903 ;; program - no need to define a new bookmark type and handler. See
1904 ;; (@> "Bookmarking Files That You Cannot Visit").
1906 ;; Note: The default value of option `bmkp-use-region' is `t', not
1907 ;; `cycling-too', which means that when you cycle to a bookmark its
1908 ;; recorded region (if any) is not activated. This is probably what
1909 ;; you want most of the time. Cycling is a repetitive action, and if
1910 ;; you cycle to a bookmark with no recorded region then an already
1911 ;; active region is just extended. Customize the value to
1912 ;; `cycling-too' if you prefer that behavior.
1915 ;;(@* "The Bookmark Navigation List")
1916 ;; *** "The Bookmark Navigation List ***
1918 ;; Bookmark+ is all about letting you define and manipulate sets of
1919 ;; bookmarks. When a bookmark set can be used for cycling (as well
1920 ;; as jumping) it is called the "navigation list" or "navlist", for
1923 ;; In other words, Bookmark+ lets you cycle among any set of
1924 ;; bookmarks. When you cycle, it is the set that currently
1925 ;; constitutes the navigation list that is cycled.
1927 ;; Here are two ways to define the navigation list:
1929 ;; * `C-x p :' (`bmkp-choose-navlist-of-type') - As the set of all
1930 ;; bookmarks of a certain type (`any' or empty input means use all
1933 ;; * `C-x p B' (`bmkp-choose-navlist-from-bookmark-list') - As the
1934 ;; set of all bookmarks corresponding to a bookmark-list bookmark,
1935 ;; that is the bookmarks corresponding to a given recorded state of
1936 ;; buffer `*Bookmark List*'.
1938 ;; Each of these lets you choose a set of bookmarks using completion.
1939 ;; For `C-x p :' you are prompted for the type of bookmark
1942 ;; For `C-x p B' you are prompted for the name of a bookmark-list
1943 ;; bookmark that you created. But you can also choose the candidate
1944 ;; `CURRENT *Bookmark List*' to capture the bookmarks that would be
1945 ;; shown currently in the `*Bookmark List*' (even if the list is not
1946 ;; displayed now). See (@> "State-Restoring Commands and Bookmarks")
1947 ;; for information about bookmark-list bookmarks.
1949 ;; If you do not define the navigation list before you start cycling,
1950 ;; it is automatically defined as follows:
1952 ;; * If you cycle using a current-buffer cycling key such as `C-x p
1953 ;; down' (see (@> "Cycling in the Current Buffer")) then the
1954 ;; bookmarks in the current buffer are used as the navlist.
1956 ;; * Otherwise, a snapshot is taken of the the bookmarks currently in
1957 ;; the global bookmark list (the value of variable
1958 ;; `bookmark-alist') as the navlist.
1960 ;; However the navlist is defined, it is important to remember this:
1961 ;; it is a static snapshot of some set of bookmarks taken at a given
1962 ;; time. Subsequent changes to the bookmark list that was copied are
1963 ;; not reflected in the navlist. If you add a bookmark it will not
1964 ;; be among those cycled. But see also
1965 ;; (@> "Cycling Dynamic Sets of Bookmarks") for how to cycle dynamic
1968 ;; You can update the navlist at any time by taking another snapshot
1969 ;; of the same bookmark list you used for the last snapshot. For the
1970 ;; global bookmark list just use `C-x p : RET'. (You can of course
1971 ;; bind that action to a shorter key sequence if you like.)
1973 ;; Besides cycling among the bookmarks of the navlist (see next),
1974 ;; once you have defined the navigation list you can use `C-x j N' or
1975 ;; `C-x 4 j N' to jump to its bookmarks, as mentioned in section
1976 ;; (@> "Different Types of Jump Commands").
1978 ;; Note that just because you might have used `C-x p B' to define the
1979 ;; navlist using a particular bookmark-list bookmark or the current
1980 ;; `*Bookmark List*' state, that does not mean that the `*Bookmark
1981 ;; List*' state at any given time necessarily reflects the navlist
1982 ;; bookmarks. The two are separate. You can, however, open the
1983 ;; `*Bookmark List*' so that it reflects the bookmarks currently in
1984 ;; the navigation list, using `C-x p N' (`bmkp-navlist-bmenu-list').
1987 ;;(@* "Cycling the Navigation List")
1988 ;; *** "Cycling the Navigation List" ***
1990 ;; So you choose a navigation list. How do you then cycle among its
1993 ;; Commands `bmkp-next-bookmark' and `bmkp-previous-bookmark' cycle
1994 ;; to the next and previous bookmark in the navigation list (with
1997 ;; You can bind these to any keys you like, but it's obviously better
1998 ;; to choose keys that are easily repeatable (e.g. by holding them
1999 ;; pressed). Some people who are used to using MS Visual Studio
2000 ;; might want to use `f2' and `S-f2' to cycle forward and backward.
2002 ;; Bookmark+ does not define such key bindings, but you can. What it
2003 ;; does is define repeatable keys on the `bookmark-map' keymap, which
2004 ;; has prefix `C-x p'. To do this it binds similar commands that can
2005 ;; be repeated by simply repeating the key-sequence suffix. These
2008 ;; Forward: `C-x p f', `C-x p C-f', `C-x p right'
2009 ;; Backward: `C-x p b', `C-x p C-b', `C-x p left'
2011 ;; (If you use an Emacs version prior to Emacs 22, you cannot use
2012 ;; this prefix-key repeatable feature.)
2014 ;; In addition, if you use MS Windows then you can invoke the Windows
2015 ;; `Open' action on each bookmark when you cycle, to act on its file
2016 ;; using the program associated with the file type. This lets you
2017 ;; play music or display images in a playlist or slideshow fashion.
2018 ;; These are the keys to do that:
2020 ;; Forward: `C-x p next' (PageDown key)
2021 ;; Backward: `C-x p prior' (PageUp key)
2023 ;; Being able to cycle among an arbitrary set of bookmarks is the
2024 ;; most important feature of Bookmark+ cycling. The other important
2025 ;; feature is that if the navigation list is defined by `*Bookmark
2026 ;; List*' then the characteristics of that bookmark display are
2027 ;; respected for navigation. Only the bookmarks visible in
2028 ;; `*Bookmark List*' are included, and the `*Bookmark List*' sort
2029 ;; order is used for navigation.
2031 ;; So you can not only choose any set of bookmarks for cycling at any
2032 ;; given time, you can also cycle among them in an order you choose.
2033 ;; For example, if in the bookmark list display (`C-x r l') you show
2034 ;; only those file bookmarks that belong to a given project, and you
2035 ;; have them sorted by file size, then cycling moves among only those
2036 ;; files, in file-size order.
2038 ;; This is a main reason you will want to define bookmark-list
2039 ;; bookmarks, which record a specific set of bookmarks and their sort
2040 ;; order: to later choose given sets in different contexts for
2044 ;;(@* "Cycling Dynamic Sets of Bookmarks")
2045 ;; *** "Cycling Dynamic Sets of Bookmarks" ***
2047 ;; The fact that the navlist is a static snapshot is a useful
2048 ;; feature, but sometimes you might want to cycle among a particular
2049 ;; dynamic set of bookmarks, that is, to have cycling take changes to
2050 ;; the bookmark set into account automatically. For that, Bookmark+
2051 ;; provides separate cycling commands for most types of bookmark.
2053 ;; By default, these different kinds of cycling commands are not
2054 ;; bound to any keys, with the exception of the commands for cycling
2055 ;; the current buffer. This exception includes cycling all bookmarks
2056 ;; for the current buffer (see (@> "Cycling in the Current Buffer")
2057 ;; and cycling only the highlighted bookmarks for the current buffer
2058 ;; (see (@> "Using Highlighted Bookmarks")). Keys `C-x p down' and
2059 ;; `C-x p C-down' are defined for these two kinds of current-buffer
2062 ;; If you often want to cycle among the bookmarks of some other
2063 ;; particular kind (e.g. only the autonamed bookmarks), then you can
2064 ;; bind the relevant commands
2065 ;; (e.g. `bmkp-next-autonamed-bookmark-repeat',
2066 ;; `bmkp-previous-autonamed-bookmark-repeat') to handy keys.
2067 ;; Otherwise, you can just use the cycling commands without binding
2071 ;;(@* "Cycling in the Current Buffer")
2072 ;; *** "Cycling in the Current Buffer" ***
2074 ;; You can navigate the bookmarks in the current buffer by cycling as
2075 ;; well as jumping. It is convenient to have dedicated keys for
2076 ;; this, separate from the keys to cycle the navigation list. The
2077 ;; following keys are defined, corresponding to commands
2078 ;; `bmkp-next-bookmark-this-buffer-repeat' and
2079 ;; `bmkp-previous-bookmark-this-buffer-repeat':
2081 ;; Next: `C-x p n', `C-x p C-n', `C-x p down'
2082 ;; Previous: `C-x p p', `C-x p C-p', `C-x p up'
2084 ;; Starting with Emacs 23.3 (Emacs fix for bug #6256), you can also
2085 ;; use the mouse wheel to cycle: `C-x p' then just rotate the wheel.
2087 ;; Again, you can bind any keys you want to these commands
2088 ;; (e.g. `f2', `S-f2'). If you do not need to use a prefix key, then
2089 ;; bind commands `bmkp-next-bookmark-this-buffer' and
2090 ;; `bmkp-previous-bookmark-this-buffer' (no -repeat).
2092 ;; You can also cycle among just the highlighted bookmarks in the
2093 ;; current buffer - see (@> "Using Highlighted Bookmarks").
2095 ;; Current-buffer cycling (all bookmarks or only the highlighted
2096 ;; ones) is dynamic: the current set of bookmarks is cycled, not a
2097 ;; static snapshot. The navlist is automatically updated to the
2098 ;; current dynamic set each time you cycle. This is different from
2099 ;; the usual cycling of the navlist, where it is taken as a static
2100 ;; snapshot - see (@> "The Bookmark Navigation List").
2102 ;; By default, you cycle the current-buffer bookmarks in order of
2103 ;; their positions in the buffer, top to bottom. If you want a
2104 ;; different order, you can customize option
2105 ;; `bmkp-this-buffer-cycle-sort-comparer'.
2107 ;; Alternatively, you can use `C-x p .' to display the `*Bookmark
2108 ;; List*' with only the current buffer's bookmarks, sort them there,
2109 ;; and then use `C-x p B' to set the navigation list to `CURRENT
2110 ;; *Bookmark List*'. In that case, you use the navlist cycling keys
2111 ;; (e.g. `C-x p f', not `C-x p n'), and the cycled set is a static
2115 ;;(@* "Autonamed Bookmarks - Easy Come Easy Go")
2116 ;; *** "Autonamed Bookmarks - Easy Come Easy Go" ***
2118 ;; Sometimes it is convenient to quickly create and delete bookmarks
2119 ;; whose names you don't really care about. That is the purpose of
2120 ;; "autonamed" bookmarks. An autonamed bookmark has a simple name
2121 ;; provided automatically, and it does not record any region
2122 ;; information - it records only a position. It is nevertheless an
2123 ;; ordinary, persistent bookmark.
2125 ;; `C-x p RET' creates a bookmark at point without prompting you for
2126 ;; the name. It is named using the current buffer name preceded by
2127 ;; the position in the buffer. For example, the autonamed bookmark
2128 ;; in buffer `foo.el' at position 58356 is `000058356 foo.el'.
2130 ;; (You can customize the format of autonamed bookmarks using options
2131 ;; `bmkp-autoname-bookmark-function' and `bmkp-autoname-format'.)
2133 ;; When you jump to any bookmark, the actual destination can differ
2134 ;; from the recorded position, because the buffer text might have
2135 ;; changed. In that case, the position you jump to has been
2136 ;; automatically relocated using the recorded bookmark context (some
2137 ;; buffer text surrounding the original position).
2139 ;; If option `bmkp-save-new-location-flag' is non-nil then, after
2140 ;; jumping, the recorded position of the bookmark is automatically
2141 ;; updated to reflect the new location jumped to. This is true for
2144 ;; In the case of an autonamed bookmark, the bookmark name reflects
2145 ;; the recorded position when you create it. And when you jump to
2146 ;; it, both the name and the recorded position are updated to reflect
2147 ;; the jump destination. So jumping to an autonamed bookmark keeps
2148 ;; its persistent record in sync with the buffer location.
2150 ;; You will thus notice that the names of autonamed bookmarks can
2151 ;; change as you visit them (e.g. cycling). The bookmarks are
2152 ;; automatically repositioned following their recorded contexts, and
2153 ;; their names reflect that repositioning.
2155 ;; `C-x p RET' is `bmkp-toggle-autonamed-bookmark-set/delete', and it
2156 ;; does double duty. If an autonamed bookmark is under the cursor,
2157 ;; then `C-x p RET' deletes it. Easy creation, easy deletion.
2158 ;; Because of this toggle behavior, there is at most one autonamed
2159 ;; bookmark at any given buffer position.
2161 ;; `C-x p RET' has a third use: With a prefix argument, it prompts
2162 ;; you to confirm the deletion of *all* autonamed bookmarks for the
2165 ;; (You can also use `C-x p delete' (that's the `delete' key), bound
2166 ;; to `bmkp-delete-bookmarks', to delete individual bookmarks under
2167 ;; the cursor or all bookmarks in the buffer. This is not limited to
2168 ;; autonamed bookmarks.)
2170 ;; In addition to `C-x p RET', you can create autonamed bookmarks
2171 ;; using these commands:
2173 ;; * `bmkp-set-autonamed-bookmark-at-line' - At a line beginning
2174 ;; * `bmkp-set-autonamed-regexp-buffer' - At buffer matches
2175 ;; * `bmkp-set-autonamed-regexp-region' - At region matches
2176 ;; * `bmkp-occur-create-autonamed-bookmarks' (`C-c b' in *Occur*) -
2177 ;; At `occur' and `multi-occur' hits
2179 ;; Autonamed bookmarks are normal bookmarks. In particular, they are
2180 ;; persisted. If you do not care to persist them, you can ensure
2181 ;; that they are automatically deleted by adding
2182 ;; `bmkp-delete-autonamed-this-buffer-no-confirm' to
2183 ;; `kill-buffer-hook' and `bmkp-delete-autonamed-no-confirm' to
2184 ;; `kill-emacs-hook':
2186 ;; (add-hook 'kill-buffer-hook
2187 ;; 'bmkp-delete-autonamed-this-buffer-no-confirm)
2188 ;; (add-hook 'kill-emacs-hook
2189 ;; 'bmkp-delete-autonamed-no-confirm)
2191 ;;(@* "Highlighting Bookmark Locations")
2192 ;; ** Highlighting Bookmark Locations **
2194 ;; You can highlight the location (destination) of a bookmark. For
2195 ;; this feature you need library `bookmark+-lit.el' in addition to
2196 ;; the other Bookmark+ libraries.
2198 ;; You might never want to highlight a bookmark, or you might want to
2199 ;; highlight most or even all bookmarks, or your use of highlighting
2200 ;; might fall somewhere between. It depends on what kind of
2201 ;; bookmarks you have and how you use them. Bookmark+ lets you
2202 ;; choose. By default, no bookmarks are highlighted.
2204 ;;(@* "Defining How to Highlight")
2205 ;; ** Defining How to Highlight **
2207 ;; By default, autonamed bookmarks are highlighted differently from
2208 ;; non-autonamed bookmarks. Bookmark highlighting uses a style and a
2209 ;; face. The available styles are these:
2211 ;; * Line - Highlight line of the bookmark position
2212 ;; * Position - Highlight character at bookmark position
2213 ;; * Line Beginning - Highlight first character on line
2214 ;; * Left Fringe - Highlight only the left fringe
2215 ;; * Left Fringe + Line - Highlight the left fringe and the line
2216 ;; * Right Fringe - Highlight only the right fringe
2217 ;; * Right Fringe + Line - Highlight the right fringe and the line
2219 ;; You can customize the default styles and faces to use for
2220 ;; autonamed and non-autonamed bookmarks. You can also customize the
2221 ;; fringe bitmaps to use.
2223 ;; * `bmkp-light-autonamed' (face)
2224 ;; * `bmkp-light-non-autonamed' (face)
2225 ;; * `bmkp-light-style-autonamed' (option)
2226 ;; * `bmkp-light-style-non-autonamed' (option)
2227 ;; * `bmkp-light-left-fringe-bitmap' (option)
2228 ;; * `bmkp-light-right-fringe-bitmap' (option)
2230 ;; In addition to the default highlighting, which you can customize,
2231 ;; you can set the highlighting for individual bookmarks and
2232 ;; particular sets of bookmarks (overriding their default
2233 ;; highlighting). These individual settings are saved as part of the
2234 ;; bookmarks themselves.
2236 ;; In the bookmark list (buffer `*Bookmark List*'):
2238 ;; * `H +' - Set the highlighting for this line's bookmark
2239 ;; * `H > +' - Set the highlighting for the marked bookmarks
2241 ;; Globally, you can use `M-x bmkp-set-lighting-for-bookmark' to set
2242 ;; the highlighting for a given bookmark.
2244 ;; Each of these commands prompts you (with completion) for the style
2245 ;; and face to set, as well as for a condition that controls whether
2246 ;; to highlight. Each of these is optional - just hit `RET' (empty
2247 ;; input) at its prompt to skip setting it.
2249 ;; The condition is an Emacs-Lisp sexp that is evaluated whenever an
2250 ;; attempt is made to highlight the bookmark. Any resulting value
2251 ;; except `:no-light' highlights the bookmark. The sexp can refer to
2252 ;; the variables `this-bookmark' and `this-bookmark-name', whose
2253 ;; values are the bookmark to be highlighted and its name,
2256 ;; So, for example, if you wanted to be prompted each time before
2257 ;; highlighting a certain bookmark you might set its highlighting
2258 ;; condition to a sexp such as this:
2260 ;; (or (y-or-n-p (format "Highlight `%s' " this-bookmark-name))
2263 ;; If you hit `n' at the prompt then `:no-light' is returned and the
2264 ;; bookmark is not highlighted.
2266 ;; In the bookmark-list display, a pink-background, one-character
2267 ;; highlight is used next to each bookmark that has a highlight
2268 ;; override wrt the default. You can see what that override setting
2269 ;; is by using `C-u C-h RET' - look for the `lighting' entry in the
2270 ;; bookmark definition.
2273 ;;(@* "Highlighting On Demand")
2274 ;; *** Highlighting On Demand ***
2276 ;; You can highlight or unhighlight a bookmark or a set of bookmarks
2279 ;; In the bookmark list (buffer `*Bookmark List*'):
2281 ;; * `H H', `H U' - Highlight, unhighlight this line's bookmark
2283 ;; * `H > H', `H > U' - Highlight, unhighlight the marked bookmarks
2287 ;; * `C-x p C-u' - Unhighlight a highlighted bookmark at
2288 ;; point or on the same line (in that order)
2290 ;; * `C-x p h', `C-x p u' - Highlight, unhighlight a bookmark in the
2291 ;; current buffer (with completion).
2293 ;; * `C-x p H', `C-x p U' - Highlight, unhighlight bookmarks:
2295 ;; With plain `C-u': all bookmarks
2297 ;; With `C-u C-u': navigation-list bookmarks
2299 ;; Otherwise, bookmarks in current buffer:
2300 ;; No prefix arg: all bookmarks
2301 ;; Prefix arg > 0: autonamed bookmarks
2302 ;; < 0: non-autonamed bookmarks
2304 ;; The default bookmark for `C-x p u' is the same bookmark that is
2305 ;; unhighlighted by `C-x p C-u': a (highlighted) bookmark at point
2306 ;; (preferably) or on the same line. The latter key binding just
2307 ;; saves you having to hit `RET' to pick the default.
2309 ;; When you use `C-x p h', you can use a prefix argument to override
2310 ;; both the default highlighting and any highlighting that is
2311 ;; recorded for the bookmark itself. You are prompted for the style
2314 ;; * Negative arg: prompted for style
2315 ;; * Non-negative arg: prompted for face
2316 ;; * Plain `C-u': prompted for style and face
2319 ;;(@* "Highlighting Automatically")
2320 ;; *** Highlighting Automatically ***
2322 ;; You can also highlight automatically, whenever you set (create) a
2323 ;; bookmark or jump to one. This is controlled by these options:
2325 ;; * `bmkp-auto-light-when-set'
2326 ;; * `bmkp-auto-light-when-jump'
2328 ;; You can choose any of these values for either option:
2330 ;; * Autonamed bookmark
2331 ;; * Non-autonamed bookmark
2333 ;; * Autonamed bookmarks in buffer
2334 ;; * Non-autonamed bookmarks in buffer
2335 ;; * All bookmarks in buffer
2336 ;; * None (no automatic highlighting) - the default
2338 ;; The first three values highlight only the bookmark being set or
2341 ;;(@* "Using Highlighted Bookmarks")
2342 ;; ** Using Highlighted Bookmarks **
2344 ;; Once you have highlighted bookmarks, what can you do with them?
2345 ;; Obviously, the highlighting can help you distinguish and find
2346 ;; bookmarks visually. But highlighting also serves as yet another
2347 ;; way to define sets: the highlighted vs unhighlighted bookmarks.
2349 ;; Any command that operates on a set of bookmarks can be applied to
2350 ;; one or the other of these two sets. Bookmark+ defines only a few
2351 ;; such operations, but you can easily define others.
2353 ;; In addition to such specific commands, you can also apply general
2354 ;; operations to the highlighted or unhighlighted bookmarks, using
2355 ;; the bookmark-list display (`*Bookmark List*'). `H S' shows only
2356 ;; the bookmarks that are currently highlighted, and `H M' marks
2357 ;; them. You can then perform any of the available bookmark-list
2358 ;; operations on them.
2360 ;; Globally, you can use these keys:
2362 ;; * `C-x p =' - List the bookmarks that are
2363 ;; highlighted at point. With a
2364 ;; prefix arg, show the full data.
2366 ;; * `C-x j h', `C-x 4 j h' - Jump to a highlighted bookmark.
2367 ;; Only highlighted bookmarks are
2368 ;; completion candidates.
2370 ;; * `C-x p C-down', `C-x p C-up' - Cycle to the next and previous
2371 ;; highlighted bookmark.
2373 ;;(@* "Use Bookmark+ with Icicles")
2374 ;; ** Use Bookmark+ with Icicles **
2376 ;; Icicles (http://www.emacswiki.org/cgi-bin/wiki/Icicles) enhances
2377 ;; your use of Bookmark+ in several ways.
2379 ;; When jumping to a bookmark, you can narrow the completion
2380 ;; candidates to bookmarks of a particular type (e.g. Info, using
2381 ;; `C-M-i'; remote, using `C-M-@'; region, using `C-M-r'). You can
2382 ;; narrow again (and again), to another bookmark type, to get the
2383 ;; intersection (e.g. remote Info bookmarks that define a region).
2385 ;; You can also narrow against different bookmark-name patterns
2386 ;; (e.g. regexps) - so-called "progressive completion". And take the
2387 ;; complement (e.g., bookmarks whose names do not match
2388 ;; `foo.*2010.*bar'). (This is not special to bookmarks; it is
2389 ;; standard Icicles practice.)
2391 ;; In Icicle mode, several of the Bookmark+ keys are remapped to
2392 ;; corresponding Icicles multi-commands. A bookmark jump key thus
2393 ;; becomes a bookmarks browser. For example, `C-x j d' browses among
2394 ;; any number of Dired bookmarks.
2396 ;; A single key can set a bookmark or visit bookmarks. This key is
2397 ;; whatever command `bookmark-set' would normally be bound to -
2398 ;; e.g. `C-x r m'. A prefix arg controls what it does. If negative
2399 ;; (`M--'), jump to (browse) bookmarks. Otherwise, set a bookmark,
2402 ;; * Numeric prefix arg (non-negative): No prompt. Use the buffer
2403 ;; name plus the text of the region (if active) or the current line
2404 ;; as the bookmark name. Quickest way to set a bookmark.
2406 ;; * No prefix arg (as usual): Prompt for bookmark name. But if the
2407 ;; region is active, use the buffer name plus the region text as
2408 ;; the default name.
2410 ;; * Plain `C-u' (as usual): Prompt for name; no bookmark overwrite.
2412 ;; During completion of a bookmark name, many features of the
2413 ;; bookmark-list display (see (@> "The Bookmark List (Display)")) are
2414 ;; available on the fly. Buffer `*Completions*' acts like a dynamic
2415 ;; version of `*Bookmark List*':
2417 ;; * Candidates are highlighted in the `*Completions*' window
2418 ;; according to their bookmark type.
2420 ;; * Candidates are Icicles multi-completions with up to three parts:
2422 ;; a. the bookmark name
2423 ;; b. the bookmark file or buffer name
2426 ;; You can match any or all of the parts. For example, you can
2427 ;; match bookmarks that have tags by typing this regexp:
2429 ;; C-M-j . * C-M-j S-TAB
2431 ;; Each `C-M-j' inserts `^G\n', which is `icicle-list-join-string',
2432 ;; the string used to join the parts. This regexp says, "match the
2433 ;; completion candidates that have all three parts (two join
2434 ;; strings)", hence some tags.
2436 ;; You can turn off the use of multi-completion candidates for
2437 ;; subsequent commands, so only bookmark names are used, by hitting
2438 ;; `M-m' in the minibuffer. You can think of this as similar to
2439 ;; using `M-t' in `*Bookmark List*' to toggle showing file names.
2440 ;; You can make not showing files and tags the default behavior by
2441 ;; customizing `icicle-show-multi-completion-flag'.
2443 ;; * You can sort completion candidates using the Bookmark+ sort
2444 ;; orders. Use `C-,' to cycle among sort orders.
2446 ;; * You can use Icicles candidate-help keys (`C-M-RET', `C-M-down',
2447 ;; etc.) to get detailed information about the current bookmark
2448 ;; candidate. `C-u C-M-RET' shows the complete, internal info
2449 ;; defining the bookmark. And without doing anything, summary info
2450 ;; about the current candidate is available in the mode line of
2451 ;; buffer `*Completions*'.
2453 ;; * You can use Icicles candidate-action keys (`C-RET', `C-mouse-2',
2454 ;; `C-down', etc.) to visit any number of bookmarks. For example,
2455 ;; holding down `C-down' cycles among the current bookmark
2456 ;; candidates, opening each in turn.
2458 ;; * You can use `S-delete' to delete the bookmark named by the
2459 ;; current candidate. You can delete any number of bookmarks this
2460 ;; way, during a single invocation of a bookmark command.
2462 ;; * You can define Icicles sets of bookmarks, persistent or not, and
2463 ;; act on their members in various ways.
2465 ;;(@* "If you use Emacs 20 and Also a More Recent Version")
2466 ;; ** If you use Emacs 20 and Also a More Recent Version **
2468 ;; This section pertains to you *ONLY* in the rare case that you use
2469 ;; both Emacs 20 and a later version, and you share the same bookmark
2470 ;; file or bookmark-list display state file between the versions.
2472 ;; By default starting with Emacs 21, Bookmark+ uses bookmark names
2473 ;; that are propertized with the full bookmark information, in order
2474 ;; to let you use multiple bookmarks with the same bookmark name. An
2475 ;; example of this is having two autofile bookmarks for files with
2476 ;; the same name in different directories.
2478 ;; When you save the bookmark list (`bookmark-alist') or a full
2479 ;; snapshot of the bookmark-list display state (e.g., using command
2480 ;; `bmkp-bmenu-define-full-snapshot-command'), these propertized
2483 ;; However, Emacs 20 cannot read a serialized version of the bookmark
2484 ;; list if it has such propertized names (the property value is a
2485 ;; list that contains the propertized string, hence circular) - it
2486 ;; will raise a read error. To avoid this, when Bookmark+ in Emacs
2487 ;; 20 saves bookmarks or a full snapshot of the bookmark-list display
2488 ;; state, it unpropertizes the bookmark names. You can read the
2489 ;; resulting files in any Emacs version.
2491 ;; But if you happen to save bookmark information using a later
2492 ;; version of Emacs (e.g. Emacs 23) and you then read that recorded
2493 ;; state using Emacs 20, the read will fail. If this happens then
2494 ;; you will need to re-save the affected file(s) using a later Emacs
2495 ;; version. In the later Emacs version:
2497 ;; 1. `M-x set-variable bmkp-propertize-bookmark-names-flag nil',
2498 ;; to stop using propertized bookmark names.
2499 ;; 2. `C-x r l' to display the bookmark list.
2500 ;; 3. `g', to refresh the display.
2501 ;; 4. `S' to save the bookmark list.
2502 ;; 5. `M-x bmkp-save-menu-list-state', to save the display state.
2504 ;; You will now be able to use your bookmarks in Emacs 20 again.
2506 ;; If you will often be going back and forth between Emacs 20 and a
2507 ;; later version, then you may prefer to simply turn off the use of
2508 ;; propertized bookmark names, to avoid the hassle mentioned above.
2509 ;; You can do that by customizing user option
2510 ;; `bmkp-propertize-bookmark-names-flag' to nil.
2512 ;; Be aware, however, that if you do that you will not be able to
2513 ;; take full advantage of Bookmark+ features such as autofile
2514 ;; bookmarks, which require the ability to have multiple bookmarks
2515 ;; with the same name. See (@> "Autofile Bookmarks").
2517 ;;(@* "Bookmark Compatibility with Vanilla Emacs (`bookmark.el')")
2518 ;; ** Bookmark Compatibility with Vanilla Emacs (`bookmark.el') **
2520 ;; Bookmark+ is generally compatible with GNU Emacs versions 20
2523 ;; 1. All bookmarks created using any version of vanilla Emacs
2524 ;; (library `bookmark.el') continue to work with Bookmark+.
2526 ;; 2. All bookmarks created using Bookmark+ will work with all Emacs
2527 ;; versions (20-23), provided you use Bookmark+ to access them.
2529 ;; 3. Most bookmarks created using Bookmark+ will not interfere with
2530 ;; the behavior of vanilla Emacs, versions 21-23. The new
2531 ;; bookmark types are simply ignored by vanilla Emacs. For
2534 ;; - A bookmark with a region is treated like a simple position
2535 ;; bookmark: the destination is the region start position.
2537 ;; - A Gnus bookmark does not work; it is simply ignored.
2539 ;; However, there are two cases in which Bookmark+ bookmarks will
2540 ;; raise an error in vanilla Emacs:
2542 ;; * You cannot use non-file (e.g. buffer-only) bookmarks with any
2543 ;; version of vanilla Emacs.
2545 ;; * You cannot use any bookmarks created using Bookmark+ with
2546 ;; vanilla Emacs 20.
2548 ;; The Emacs bookmark data structure has changed from version to
2549 ;; version. Bookmark+ always creates bookmarks that have the most
2550 ;; recent structure (Emacs 23). As is the case for any bookmarks
2551 ;; that have the Emacs 23 structure, these bookmarks will not work
2552 ;; in vanilla Emacs 20 (that is, without Bookmark+).
2554 ;; Bottom line: Use `bookmark+.el' to access bookmarks created using
2557 ;;(@* "New Bookmark Structure")
2558 ;; ** New Bookmark Structure **
2560 ;; The bookmark data structure, variable `bookmark-alist', has been
2561 ;; enhanced to support new bookmark types. For a description of this
2562 ;; enhanced structure, use `C-h v bookmark-alist'.
2564 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2566 ;; This program is free software; you can redistribute it and/or modify
2567 ;; it under the terms of the GNU General Public License as published by
2568 ;; the Free Software Foundation; either version 3, or (at your option)
2569 ;; any later version.
2571 ;; This program is distributed in the hope that it will be useful,
2572 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
2573 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2574 ;; GNU General Public License for more details.
2576 ;; You should have received a copy of the GNU General Public License
2577 ;; along with this program; see the file COPYING. If not, write to
2578 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
2579 ;; Floor, Boston, MA 02110-1301, USA.
2581 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2585 ;; You need not load this file. It contains only documentation.
2587 (provide 'bookmark+-doc)
2589 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2590 ;;; bookmark+-doc.el ends here