New org capture template
[emacs.git] / .emacs.d / elisp / icicle / bookmark+-doc.el
1 ;;; bookmark+-doc.el - Documentation for package Bookmark+.
2 ;;
3 ;; Filename: bookmark+-doc.el
4 ;; Description: Documentation for package Bookmark+
5 ;; Author: Drew Adams
6 ;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
7 ;; Copyright (C) 2000-2012, Drew Adams, all rights reserved.
8 ;; Created: Fri Sep 15 07:58:41 2000
9 ;; Last-Updated: Tue May 1 08:58:36 2012 (-0700)
10 ;; By: dradams
11 ;; Update #: 14564
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
16 ;;
17 ;; Features that might be required by this library:
18 ;;
19 ;; None
20 ;;
21 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
22 ;;
23 ;;; Commentary:
24 ;;
25 ;; Documentation for the Bookmark+ package, which provides
26 ;; extensions to standard library `bookmark.el'.
27 ;;
28 ;; The Bookmark+ libraries are these:
29 ;;
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
36 ;;
37 ;; `bookmark+-doc.el' - documentation (comment-only - this file)
38 ;; `bookmark+-chg.el' - change log (comment-only file)
39 ;;
40 ;; The documentation includes how to byte-compile and install
41 ;; Bookmark+. It is also available in these ways:
42 ;;
43 ;; 1. From the bookmark list (`C-x p e' or `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
46 ;; Web'.
47 ;;
48 ;; 2. From the Emacs-Wiki Web site:
49 ;; http://www.emacswiki.org/cgi-bin/wiki/BookmarkPlus.
50 ;;
51 ;; 3. From the Bookmark+ group customization buffer:
52 ;; `M-x customize-group bookmark-plus', then click link
53 ;; `Commentary'.
54 ;;
55 ;; (The commentary links in #1 and #3 work only if put you this
56 ;; library, `bookmark+-doc.el', in your `load-path'.)
57 ;;
58 ;; More description below.
59 ;;
60 ;;
61 ;; ****** NOTE ******
62 ;;
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.
68 ;;
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:
72 ;;
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.
76 ;;
77 ;; 2. In your default bookmark file, `bookmark-default-file'
78 ;; (`.emacs.bmk'), and in any other bookmark files you might
79 ;; have.
80 ;;
81 ;; 3. In your `*Bookmark List*' state file,
82 ;; `bmkp-bmenu-state-file' (`~/.emacs-bmk-bmenu-state.el').
83 ;;
84 ;; 4. In your `*Bookmark List*' commands file,
85 ;; `bmkp-bmenu-commands-file' (`~/.emacs-bmk-bmenu-commands.el'),
86 ;; if you have one.
87 ;;
88 ;; You can do this editing in a virgin Emacs session (`emacs
89 ;; -Q'), that is, without loading Bookmark+.
90 ;;
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.
96 ;;
97 ;; To turn off this automatic saving, you can use `M-~' and
98 ;; `C-M-~' 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).
102 ;;
103 ;;
104 ;; Again, sorry for this inconvenience.
105
106 ;;(@> "Index")
107 ;;
108 ;; Index
109 ;; -----
110 ;;
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.
117 ;;
118 ;; (@> "Documentation")
119 ;; (@> "Installing Bookmark+")
120 ;; (@> "Bookmark+ Features")
121 ;; (@> "Bookmark Basics")
122 ;; (@> "Different Types of Jump Commands")
123 ;; (@> "Bookmark Tags")
124 ;; (@> "Bookmark Tags Can Have Values")
125 ;; (@> "Function, Sequence, and Variable-List Bookmarks")
126 ;; (@> "Editing Bookmarks")
127 ;; (@> "Bookmark Records: What A Bookmark Looks Like")
128 ;; (@> "Bookmark-List Views - Saving and Restoring State")
129 ;; (@> "Quitting Saves the Bookmark-List State")
130 ;; (@> "State-Restoring Commands and Bookmarks")
131 ;; (@> "Bookmarking without Visiting the Target")
132 ;; (@> "Bookmarking a File or a URL")
133 ;; (@> "Bookmarking the Marked Files in Dired")
134 ;; (@> "Bookmarking Compilation, Grep, and Occur Hits")
135 ;; (@> "Bookmarking Files That You Cannot Visit with Emacs")
136 ;; (@> "Opening Bookmarks Using Windows File Associations")
137 ;; (@> "Autofile Bookmarks")
138 ;; (@> "A Type-Aware `find-file'")
139 ;; (@> "Tagging Files")
140 ;; (@> "Using Multiple Bookmark Files")
141 ;; (@> "Bookmark-File Bookmarks")
142 ;; (@> "The Bookmark List Display")
143 ;; (@> "Tag Commands and Keys")
144 ;; (@> "Tags: Sets of Bookmarks")
145 ;; (@> "Open Dired for the Marked File Bookmarks")
146 ;; (@> "Marking and Unmarking Bookmarks")
147 ;; (@> "Filtering Bookmarks (Hiding and Showing)")
148 ;; (@> "Only Visible Bookmarks Are Affected")
149 ;; (@> "Omitting Bookmarks from Display")
150 ;; (@> "Sorting Bookmarks")
151 ;; (@> "Bookmarks for Specific Files or Buffers")
152 ;; (@> "Cycling, Navigation List")
153 ;; (@> "The Bookmark Navigation List")
154 ;; (@> "Cycling the Navigation List")
155 ;; (@> "Cycling Dynamic Sets of Bookmarks")
156 ;; (@> "Cycling in the Current File/Buffer")
157 ;; (@> "Autonamed Bookmarks - Easy Come Easy Go")
158 ;; (@> "Temporary Bookmarks")
159 ;; (@> "Temporary Bookmarking Mode")
160 ;; (@> "Making Bookmarks Temporary")
161 ;; (@> "Automatic Bookmarking")
162 ;; (@> "Highlighting Bookmark Locations")
163 ;; (@> "Defining How to Highlight")
164 ;; (@> "Highlighting On Demand")
165 ;; (@> "Highlighting Automatically")
166 ;; (@> "Using Highlighted Bookmarks")
167 ;; (@> "Use Bookmark+ with Icicles")
168 ;; (@> "If you use Emacs 20 and Also a More Recent Version")
169 ;; (@> "Bookmark Compatibility with Vanilla Emacs (`bookmark.el')")
170 ;; (@> "New Bookmark Structure")
171
172 ;;(@* "Documentation")
173 ;;
174 ;; Documentation
175 ;; -------------
176 ;;
177 ;;(@* "Installing Bookmark+")
178 ;; ** Installing Bookmark+ **
179 ;;
180 ;; The main Bookmark+ library is `bookmark+.el'. The other required
181 ;; libraries are `bookmark+-mac.el', `bookmark+-bmu.el',
182 ;; `bookmark+-1.el', and `bookmark+-key.el'. If you want to be able
183 ;; to highlight bookmarks then you will also need library
184 ;; `bookmark+-lit.el'. I recommend that you byte-compile all of the
185 ;; libraries, after loading the source files (in particular, load
186 ;; `bookmark+-mac.el').
187 ;;
188 ;; Put the directory of these libraries in your `load-path' and add
189 ;; this to your init file (~/.emacs):
190 ;;
191 ;; (require 'bookmark+)
192 ;;
193 ;; That will load all of the Bookmark+ libraries. If you do not care
194 ;; about bookmark highlighting then simply do not put
195 ;; `bookmark+-lit.el' in your `load-path'.
196 ;;
197 ;; By default (see option `bmkp-crosshairs-flag'), when you visit a
198 ;; bookmark that has no region it is highlighted temporarily using
199 ;; crosshairs, for easy recognition. (This temporary highlighting is
200 ;; independent of the highlighting provided by `bookmark+-lit.el'.)
201 ;;
202 ;; For this optional crosshairs feature you also need library
203 ;; `crosshairs.el', which in turn requires libraries `col-highlight',
204 ;; `hl-line', `hl-line+', and `vline'. Library `hl-line' comes with
205 ;; vanilla Emacs. The others are available from the Emacs Wiki web
206 ;; site: http://www.emacswiki.org/. You also need Emacs 22 or later
207 ;; for this feature.
208
209 ;;(@* "Bookmark+ Features")
210 ;; ** Bookmark+ Features **
211 ;;
212 ;; Here is an overview of some of the features that Bookmark+
213 ;; provides. Some of these are detailed in other sections, below.
214 ;;
215 ;; * Richer bookmarks. They record more. They are more accurate.
216 ;;
217 ;; - You can tag bookmarks, a la del.icio.us. In effect, tags
218 ;; define bookmark sets. A bookmark can have any number of
219 ;; tags, and multiple bookmarks can have the same tag. You can
220 ;; sort, show/hide, or mark bookmarks based on their tags.
221 ;;
222 ;; - Bookmark+ tags can be more than just names. They can be
223 ;; full-fledged user-defined attributes, with Emacs-Lisp objects
224 ;; as their values.
225 ;;
226 ;; - You can have multiple bookmarks with the same name. This is
227 ;; particularly useful for autofile bookmarks, which are
228 ;; bookmarks that have the same name as their target files.
229 ;; They give you the effect of using files themselves as
230 ;; bookmarks. In particular, they let you, in effect, tag
231 ;; files. See (@> "Autofile Bookmarks") and
232 ;; (@> "Tagging Files").
233 ;;
234 ;; (In vanilla Emacs you can also, in theory, have multiple
235 ;; bookmarks with the same name. But you cannot really use them
236 ;; in any practical way. Vanilla Emacs cannot distinguish among
237 ;; them: the most recent one shadows all others with the same
238 ;; name.)
239 ;;
240 ;; - Bookmarks record the number of times you have visited them
241 ;; and the time of the last visit. You can sort, show/hide, or
242 ;; mark bookmarks based on this info.
243 ;;
244 ;; - You can combine bookmarks, to make composite, or sequence,
245 ;; bookmarks. Invoking a sequence bookmark invokes each of its
246 ;; component bookmarks in turn. A component bookmark can itself
247 ;; be a sequence bookmark.
248 ;;
249 ;; - You can bookmark a region of text, not just a position. When
250 ;; you jump to a bookmark that records a region, the region is
251 ;; activated (see option `bmkp-use-region'). (Region activation
252 ;; is not supported for Gnus bookmarks.)
253 ;;
254 ;; - Bookmarks are relocated better than for vanilla Emacs when
255 ;; the contextual text changes.
256 ;;
257 ;; * Additional types of bookmarks.
258 ;;
259 ;; - Autofile bookmarks. You can bookmark a file without visiting
260 ;; it or naming the bookmark. The bookmark name is the same as
261 ;; the file name (non-directory part). You can have multiple
262 ;; such bookmarks with the same name, to bookmark files with the
263 ;; same name but in different directories.
264 ;;
265 ;; - Dired bookmarks. You can bookmark a Dired buffer, recording
266 ;; and restoring its `ls' switches, which files are marked,
267 ;; which subdirectories are inserted, and which (sub)directories
268 ;; are hidden.
269 ;;
270 ;; - Bookmark-list bookmarks. You can bookmark the current state
271 ;; of buffer `*Bookmark List*' - a list of bookmarks. Jumping
272 ;; to such a bookmark restores the recorded sort order,
273 ;; markings, filter, title, and omit list.
274 ;; See (@> "Omitting Bookmarks from Display").
275 ;;
276 ;; - Bookmark-file bookmarks. You can bookmark a bookmark file.
277 ;; Jumping to such a bookmark loads the bookmarks in the file.
278 ;; See (@> "Bookmark-File Bookmarks").
279 ;;
280 ;; - Desktop bookmarks. You can bookmark the current Emacs
281 ;; desktop, as defined by library `desktop.el' - use command
282 ;; `bmkp-set-desktop-bookmark' (`C-x p K'). You can "jump" to
283 ;; (that is, restore) a saved desktop. A desktop includes:
284 ;;
285 ;; - Some global variables. To exclude variables normally
286 ;; saved, see option `bmkp-desktop-no-save-vars'.
287 ;; - The current set of buffers and their associated files.
288 ;; For each: its mode, point, mark, & some local variables.
289 ;;
290 ;; - Gnus bookmarks. You can bookmark a Gnus article, a URL, a
291 ;; PDF file (DocView), a UNIX manual page (from the output of
292 ;; Emacs command `man' or `woman'), an image, or a piece of
293 ;; music.
294 ;;
295 ;; - Non-file (buffer) bookmarks. You can bookmark a buffer that
296 ;; is not associated with a file.
297 ;;
298 ;; - Function bookmarks. A bookmark can represent a Lisp
299 ;; function, which is invoked when you "jump" to the bookmark.
300 ;;
301 ;; - Sequence (composite) bookmarks. A bookmark can represent a
302 ;; sequence of other bookmarks.
303 ;;
304 ;; - Lisp variable bookmarks. A bookmark can represent a set of
305 ;; variables and their values.
306 ;;
307 ;; In particular, note that you can use the following kinds of
308 ;; bookmarks to quickly switch among different projects (sets of
309 ;; bookmarks): Dired, bookmark-list, bookmark-file, and desktop
310 ;; bookmarks.
311 ;;
312 ;; * Additional ways to bookmark.
313 ;;
314 ;; - You can bookmark the file or URL named at point (or any other
315 ;; file or URL), without first visiting it.
316 ;;
317 ;; - You can bookmark the targets of the hits in a compilation
318 ;; buffer or an `occur' buffer, without first visiting them.
319 ;;
320 ;; - You can bookmark all of the marked files in Dired at once.
321 ;;
322 ;; * Extensive menus.
323 ;;
324 ;; - In the `*Bookmark List*' display, a `mouse-3' popup menu has
325 ;; actions for the individual bookmark that you point to when
326 ;; you click the mouse.
327 ;;
328 ;; - In the `*Bookmark List*' display, a complete menu-bar menu,
329 ;; `Bookmark+', is available. The same menu is available on
330 ;; `C-mouse-3'. It has submenus `Jump To', `Mark', `Omit',
331 ;; `Show', `Sort', `Tags', `Highlight' (needs library
332 ;; `bookmark+-lit.el), and `Define Command'.
333 ;;
334 ;; - The vanilla `Bookmarks' menu, which is typically a submenu of
335 ;; the menu-bar `Edit' menu, is modified by adding several items
336 ;; from the `Bookmark+' menu, including submenus `Jump To',
337 ;; `Tags', and `Highlight'.
338 ;;
339 ;; * Improvements for the bookmark-list display.
340 ;;
341 ;; This is buffer `*Bookmark List*', aka the bookmark "menu list"
342 ;; (a misnomer), which you display using `C-x p e' (or `C-x r l').
343 ;; See (@> "The Bookmark List Display").
344 ;;
345 ;; - The last display state is saved (by default), and is restored
346 ;; the next time you show the list. (Tip: Use the bookmark list
347 ;; as your "Home" page at Emacs startup.)
348 ;;
349 ;; - You can save the current bookmark-list state at any time and
350 ;; return to it later. There are a few ways to do this,
351 ;; including bookmarking the list itself.
352 ;; See (@> "Bookmark-List Views - Saving and Restoring State").
353 ;;
354 ;; - Marking/unmarking is enhanced. It is similar to Dired's.
355 ;;
356 ;; - You can easily mark or show different classes of bookmarks.
357 ;;
358 ;; - Faces distinguish bookmarks by type.
359 ;;
360 ;; - You can sort bookmarks in many ways. You can easily define
361 ;; your own sort orders, even complex ones.
362 ;;
363 ;; - You can regexp-search (`M-a') or query-replace (`M-q') the
364 ;; targets (destination file or buffers) of the marked
365 ;; bookmarks, in the current bookmark-list sort order. For
366 ;; Emacs 23 and later, you can even search incrementally (`M-s a
367 ;; C-s', or `M-s a C-M-s' for regexp).
368 ;;
369 ;; - You can use `M-d >' to open Dired for just the local file
370 ;; bookmarks that are marked (`>').
371 ;;
372 ;; - If you use Emacs on Microsoft Windows, you can open bookmarks
373 ;; according to Windows file associations. (You will also need
374 ;; library `w32-browser.el'.)
375 ;;
376 ;; - You can use (lax) completion when you set a bookmark using
377 ;; `bookmark-set' (`C-x r m'), choosing from existing bookmarks
378 ;; for the same buffer. This makes it easy to update a nearby
379 ;; bookmark (e.g. relocate it). With a numeric prefix argument
380 ;; (or if there are no bookmarks for the buffer), you can choose
381 ;; from all bookmarks.
382 ;;
383 ;; - You can edit a bookmark: its name and file name/location, its
384 ;; tags, or its complete defining internal Lisp record.
385 ;;
386 ;; * Multiple bookmark files.
387 ;;
388 ;; - Although vanilla Emacs lets you load different bookmark
389 ;; files, it does not support this feature well, and the
390 ;; behavior can even be contradictory. With Bookmark+ you can
391 ;; easily (a) switch among alternative bookmark files or (b)
392 ;; load multiple files into the same session, accumulating their
393 ;; bookmark definitions. The last file you used is the default
394 ;; when you choose a file to switch to, so it is easy to go back
395 ;; and forth between two bookmark files.
396 ;; See (@> "Using Multiple Bookmark Files").
397 ;;
398 ;; * Type-specific jump commands.
399 ;;
400 ;; - When you want to jump to a bookmark of a specific type
401 ;; (e.g. Dired), you can use a command that offers only such
402 ;; bookmarks as completion candidates.
403 ;;
404 ;; * Dedicated keymaps as prefix keys.
405 ;;
406 ;; - Prefix `C-x p' is used for bookmark keys, in general. The
407 ;; vanilla keys on prefix `C-x r' are still available also, but
408 ;; that prefix is shared with register commands, making it less
409 ;; convenient for bookmarks. Using `C-x p' lets you focus on
410 ;; bookmarks.
411 ;;
412 ;; - Prefix `C-x p c' is for setting various kinds of bookmarks.
413 ;;
414 ;; - Prefixes `C-x j' and `C-x 4 j' (for other-window) are used
415 ;; for bookmark jump commands. Again, a dedicated prefix key
416 ;; helps you focus on one kind of action (jumping).
417 ;;
418 ;; All of these prefix keys correspond to prefix-map variables, so
419 ;; you need not use these particular prefixes. You can bind these
420 ;; maps to any prefix keys you want. These are the maps, together
421 ;; with their predefined bindings. (Note that the keymap for
422 ;; setting bookmarks is bound to a prefix in `bookmark-map'.)
423 ;;
424 ;; `bookmark-map' - `C-x p'
425 ;; `bmkp-set-map' - `C-x p c'
426 ;; `bmkp-jump-map' - `C-x j'
427 ;; `bmkp-jump-other-window-map' - `C-x 4 j'
428 ;;
429 ;; In addition, mode-specific bookmarking commands are bound in
430 ;; some other modes: Occur, Compilation (including Grep),
431 ;; Buffer-menu, Gnus, Info, Man, Woman, W3M, and Dired (if you use
432 ;; Dired+). These keys let you set or jump to bookmarks specific
433 ;; to the modes.
434 ;;
435 ;; * Helpful help.
436 ;;
437 ;; - Information about individual bookmarks.
438 ;;
439 ;; . Anywhere in Emacs, `C-x p ?' (command
440 ;; `bmkp-describe-bookmark') describes any bookmark. With a
441 ;; prefix argument, it shows you the full information that
442 ;; defines it (internal form).
443 ;;
444 ;; . In the bookmark list, `C-h RET' (or `C-h C-RET') describes
445 ;; the bookmark under the cursor. The description is as
446 ;; complete as possible - for example, for an image-file
447 ;; bookmark the complete EXIF image metadata is shown. (This
448 ;; is only for Emacs 22 and later, and only if you have
449 ;; command-line tool `exiftool' installed. See standard Emacs
450 ;; library `image-dired.el' for more information about
451 ;; `exiftool'.)
452 ;;
453 ;; And again, a prefix arg (`C-u C-h RET') means show the full
454 ;; (internal) bookmark information.
455 ;;
456 ;; - General Bookmark+ documentation.
457 ;;
458 ;; . Anywhere in Emacs, `M-x bmkp-bmenu-mode-status-help' shows
459 ;; detailed information about the current state of the
460 ;; bookmark list. Click button `Doc in Commentary' or button
461 ;; `Doc on the Web' to access the complete documentation.
462 ;;
463 ;; (Use button `Customize' to customize all '''Bookmark+'''
464 ;; faces and options.)
465 ;;
466 ;; . In the bookmark list, `?' and `C-h m' are the same as `M-x
467 ;; bmkp-bmenu-mode-status-help'. (`C-h m' in the bookmark
468 ;; list does not show you info about minor modes. If you want
469 ;; that, use `M-x describe-mode'.)
470 ;;
471 ;; . In the `bookmark-plus' group customization buffer (`M-x
472 ;; customize-group bookmark-plus'), click button `Commentary'.
473 ;;
474 ;; . From the Emacs-Wiki Web site,
475 ;; http://www.emacswiki.org/cgi-bin/wiki/BookmarkPlus.
476 ;;
477 ;; - It is easy to recognize orphaned and invalid bookmarks.
478 ;;
479 ;; . Invalid bookmarks are shown in a special face in the
480 ;; bookmark-list display.
481 ;;
482 ;; . You can easily mark all of the orphaned bookmarks, that is,
483 ;; those whose recorded files have been renamed or deleted.
484 ;; You can then relocate or delete those bookmarks.
485 ;;
486 ;; - It is easy to recognize modified (i.e., unsaved) bookmarks.
487 ;; They are marked with `*'. Likewise, bookmarks that have tags
488 ;; (marked with `t'); bookmarks that have annotations (`a'); and
489 ;; bookmarks that are temporary (`X'), meaning that they will
490 ;; not be saved.
491 ;;
492 ;; * Jump-destination highlighting.
493 ;;
494 ;; - When you jump to a bookmark, the destination (position) is
495 ;; highlighted temporarily using crosshairs, to make it stand
496 ;; out. Option `bmkp-crosshairs-flag' controls this, and this
497 ;; feature is available only if you also use library
498 ;; `crosshairs.el'.
499 ;;
500 ;; * Visual bookmarks (highlighting).
501 ;;
502 ;; - You can highlight the locations of bookmarks, either
503 ;; automatically or on demand. You control what kind of
504 ;; highlighting, if any, is used for which bookmarks. This
505 ;; feature requires that you have library `bookmark+-lit.el' in
506 ;; your `load-path' (it will then be loaded by `bookmark+.el).
507 ;;
508 ;; * Better, user-configurable bookmark-name defaults.
509 ;;
510 ;; See the doc strings of command `bookmark-set' (Bookmark+
511 ;; version) and options `bmkp-new-bookmark-default-names' and
512 ;; `bmkp-default-bookmark-name'.
513 ;;
514 ;; * Synergy with Icicles.
515 ;;
516 ;; - Icicles works with Bookmark+ to provide enhanced bookmark
517 ;; jumping (visiting), setting, and help. It gives you a
518 ;; bookmark browser, and lets you bookmark and tag files on the
519 ;; fly. See (@> "Use Bookmark+ with Icicles") and
520 ;; http://www.emacswiki.org/cgi-bin/wiki/Icicles.
521
522 ;;(@* "Bookmark Basics")
523 ;; ** Bookmark Basics **
524 ;;
525 ;; Bookmark+ builds on vanilla Emacs bookmarks. If you are familiar
526 ;; with the latter, then you can skip this section, which mostly
527 ;; reviews the former. However, this section also introduces some
528 ;; Bookmark+ concepts and features that are detailed in other
529 ;; sections.
530 ;;
531 ;; In Emacs bookmarking these three things are different but related:
532 ;;
533 ;; 1. the bookmark list
534 ;; 2. the bookmark file
535 ;; 3. the bookmark-list display (buffer `*Bookmark List*', aka the
536 ;; bookmark "menu list", a misnomer)
537 ;;
538 ;; It is important to keep these three straight and understand their
539 ;; differences in practice, in particular, when they do and do not
540 ;; represent the same set of bookmarks.
541 ;;
542 ;; #1 is in memory. It is the current set of bookmarks. When you
543 ;; add, rename, delete, etc. a bookmark, this list is updated.
544 ;;
545 ;; #2 is on disk. It is a persistent record of a set of bookmarks.
546 ;;
547 ;; The bookmark list (#1) is the current value of internal variable
548 ;; `bookmark-alist'. The bookmark file (#2)can be anywhere. Its
549 ;; default filename is the value of user option
550 ;; `bookmark-default-file'.
551 ;;
552 ;; The bookmark list is typically initialized from the bookmark file
553 ;; - referred to as loading your bookmarks, but you can also create
554 ;; bookmarks (adding them to the list) without ever saving them to
555 ;; disk.
556 ;;
557 ;; The bookmark list can be saved to the bookmark file - referred to
558 ;; as saving your bookmarks - either automatically or on demand. But
559 ;; it is not necessarily saved. Even if it has been saved in the
560 ;; past, that does not mean that at any given time the bookmark list
561 ;; corresponds exactly to the bookmark file.
562 ;;
563 ;; The list and the file can often become out of sync. In an Emacs
564 ;; session, the bookmark list rules. After an Emacs session, the
565 ;; bookmark file rules (it is all there is). You can use `C-x p L'
566 ;; (`bmkp-switch-bookmark-file-create') to sync (revert) the list to
567 ;; reflect the file - just accept the default value, "switching" to
568 ;; the same file.
569 ;;
570 ;; The bookmark-list display (#3) is a snapshot view of the bookmarks
571 ;; in the bookmark list. As such, what you see there reflects the
572 ;; state of the bookmark list at some point in time. So here again,
573 ;; the two, list and display, can be out of sync. Hitting `g' in the
574 ;; bookmark-list display refreshes it to accurately reflect the
575 ;; current bookmark list (#1). Some other operations in the display
576 ;; also keep it synced with the list.
577 ;;
578 ;; Using a prefix argument (`C-u g') syncs the display (#3) and the
579 ;; list (#1) to the file (#2). This can be useful when some other
580 ;; process (e.g., another Emacs session) updates the bookmark file or
581 ;; when you want to abandon changes to the current bookmark list and
582 ;; any of the current bookmarks. Outside the bookmark-list display,
583 ;; you can use command `bmkp-revert-bookmark-file' to do this.
584 ;;
585 ;; You can load different bookmark files, either adding their
586 ;; bookmarks to those already in the current bookmark list or
587 ;; replacing them.
588 ;;
589 ;; The most important takeaway from this section is that #1 (list),
590 ;; #2 (file), and #3 (display) can be out of sync, and they often
591 ;; are. And that can be useful.
592 ;;
593 ;; Until now, everything said in this section is true of vanilla
594 ;; Emacs as well as Bookmark+. Bookmark+ adds some flexibility
595 ;; regarding the use of multiple bookmark files, and it can save the
596 ;; last state of the bookmark-list display for later reuse.
597 ;;
598 ;; The saved state of the display is restored when you show the
599 ;; display after quitting it (`q') in the same session or quitting
600 ;; Emacs, but only if the bookmark file whose location it recorded is
601 ;; the same as the current bookmark file.
602 ;;
603 ;; It would not make sense to display a completely different set of
604 ;; bookmarks from those that are currently loaded. The display must
605 ;; always reflect the current bookmark list (even if it sometimes
606 ;; reflects it imperfectly, because it is a snapshot). So if the
607 ;; bookmark file that is loaded is different from the one that was
608 ;; recorded for the display state, the recorded state is ignored.
609 ;;
610 ;;(@* "Automatic Saving")
611 ;; *** Automatic Saving ***
612 ;;
613 ;; User option `bookmark-save-flag' controls whether and how often to
614 ;; automatically save the bookmark list to the bookmark file, thus
615 ;; syncing the two. You can toggle this option using `M-~' in the
616 ;; bookmark-list display.
617 ;;
618 ;; In the bookmark-list display, you can tell whether individual
619 ;; bookmarks have been modified since the last save: they are marked
620 ;; with `*'. I believe that this indication is robust and accurate
621 ;; (if not, please report a bug), but a word of caution: do not
622 ;; depend on it. The only way to be sure that your bookmarks have
623 ;; been saved is to save them. ;-)
624 ;;
625 ;; Is there a way to unmodify a single bookmark that you have
626 ;; changed? No, not unless it is the only one you modified. If you
627 ;; revert to the bookmarks as last saved, then all changes to all
628 ;; bookmarks (including addition and removal of bookmarks) are lost.
629 ;; If you want to work carefully when making multiple changes, then
630 ;; save any modifications you are sure of before you move on to
631 ;; others. If only one bookmark is modified then reverting to the
632 ;; bookmark file effectively unmodifies that bookmark.
633 ;;
634 ;; When you consult the doc for option `bookmark-save-flag' you see
635 ;; that besides values of `nil' and `t', meaning off and on, it can
636 ;; have a value that is the number of bookmark modifications to allow
637 ;; before automatically saving. If the value is 10, for instance,
638 ;; then the 11th modification triggers automatic saving.
639 ;;
640 ;; But a modification means any change to any bookmark. Typically,
641 ;; you are more interested in considering all of the changes caused
642 ;; by a given command as one modification. Why? Suppose you use a
643 ;; command such as `T > +' (`bmkp-bmenu-add-tags-to-marked'), which
644 ;; adds a set of tags to each of the marked bookmarks. Even if there
645 ;; have been no other modifications since you last saved bookmarks,
646 ;; if there are more marked bookmarks than your setting of
647 ;; `bookmark-save-flag' then automatic saving will kick in in the
648 ;; middle of the command. Some of the bookmarks with the added tags
649 ;; will be automatically saved. And that does not give you an
650 ;; opportunity to cancel the changes (e.g., by quitting without
651 ;; saving).
652 ;;
653 ;; This is the reason for option `bmkp-count-multi-mods-as-one-flag',
654 ;; whose default value is `t', which means count all of a sequence of
655 ;; modifications together as one modification, as far as
656 ;; `bookmark-save-flag' is concerned.
657
658 ;;(@* "Different Types of Jump Commands")
659 ;; ** Different Types of Jump Commands **
660 ;;
661 ;; When you jump to a bookmark, you can use completion to specify the
662 ;; bookmark name. `bookmark-jump' and `bookmark-jump-other-window',
663 ;; bound to `C-x j j' and `C-x 4 j j', are general commands. Their
664 ;; completion candidates include all of your bookmarks. With
665 ;; Bookmark+ you can easily have a large number of bookmarks.
666 ;;
667 ;; To provide more specificity, Bookmark+ provides many different
668 ;; bookmark jump commands. If you want to jump to a bookmark of a
669 ;; specific type, such as Info, you can use a Bookmark+ command that
670 ;; is specific to bookmarks of that type: only those bookmarks are
671 ;; completion candidates.
672 ;;
673 ;; There are thus type-specific commands: `bmkp-dired-jump',
674 ;; `bmkp-info-jump', and so on, bound to `C-x j d', `C-x j i', and so
675 ;; on. There are also commands to jump to bookmarks for the current
676 ;; buffer or for particular buffers or files
677 ;; (see (@> "Bookmarks for Specific Files or Buffers")).
678 ;;
679 ;; All bookmark jump commands are bound to keys that have the prefix
680 ;; `C-x j'. There is an other-window version of most jump commands,
681 ;; and it is bound to the same key as the same-window command, except
682 ;; the prefix is `C-x 4 j', not `C-x j'. For instance,
683 ;; `bmkp-dired-jump-other-window' is bound to `C-x 4 j d'.
684 ;;
685 ;; More precisely, the bookmark jump commands are on the prefix maps
686 ;; `bmkp-jump-map' and `bmkp-jump-other-window-map', which have the
687 ;; default bindings `C-x j' and `C-x 4 j'. You can bind these maps
688 ;; to any keys you like.
689 ;;
690 ;; If you do not remember the different type-specfic bindings, you
691 ;; can use commands `bmkp-jump-to-type' and
692 ;; `bmkp-jump-to-type-other-window' (`C-x j :' and `C-x 4 j :').
693 ;; They work for any type, prompting you first for the type, then for
694 ;; a bookmark of that type (only).
695 ;;
696 ;; There are several commands for jumping to a bookmark with tags.
697 ;; The completion candidates can be those bookmarks that have all
698 ;; tags in a given set, some tags in a given set, all tags matching a
699 ;; regexp, or some tags matching a regexp. You are prompted for the
700 ;; set of tags or the regexp to match.
701 ;;
702 ;; These commands all have the prefix key `C-x j t'. The suffix key
703 ;; is `*' for "all" and `+' for "some". The regexp-matching commands
704 ;; precede the suffix key with `%'. For example, `C-x j t % +' jumps
705 ;; to a bookmark you choose that has one or more tags that match the
706 ;; regexp you input.
707 ;;
708 ;; There are some type-specific jump commands for bookmarks with
709 ;; tags. The key sequences for these include a key that indicates
710 ;; the bookmark type, after the `t' indicating tags. For example,
711 ;; commands for jumping to a file or directory bookmark having
712 ;; certain tags use the prefix `C-x j t f' (`f' for file). Similar
713 ;; commands for autofile bookmarks have prefix `C-x j t a' (`a' for
714 ;; autofile).
715 ;;
716 ;; For example, `C-x j t f % *' jumps to a file or directory bookmark
717 ;; you choose, where all of its tags match a regexp, and `C-x j t a
718 ;; +' finds a file tagged with at least one of the tags you input.
719 ;;
720 ;; In addition to the ordinary autofile "jump" commands, there are
721 ;; `find-file' versions: they read a file name using
722 ;; `read-file-name', instead of completing a bookmark name. - see
723 ;; (@> "Autofile Bookmarks"). These commands are available starting
724 ;; with Emacs 22.
725 ;;
726 ;; Bookmark names are global. File names are not; that is, the
727 ;; non-directory portion is not. Suppose you have two similar
728 ;; directories with some like-named files, perhaps tagged in similar
729 ;; ways. Imagine image files of your vacations organized in
730 ;; different directories by year. It is sometimes useful to narrow
731 ;; your focus to the file bookmarks in one directory.
732 ;;
733 ;; Commands such as `bmkp-file-this-dir-jump' (`C-x j . f') offer as
734 ;; completion candidates only bookmarks for files and subdirs in the
735 ;; current directory (`default-directory'). For tags, there are
736 ;; equivalent commands. For example, `C-x j t . % *' is the same as
737 ;; `C-x j t f % *', but the destinations are limited to files in the
738 ;; current directory. All of the "this-dir" file jump commands are
739 ;; bound to the same keys as the general file jump commands, but with
740 ;; `.' instead of `f'.
741 ;;
742 ;; Remember that Bookmark+ collects lots of commands on only a few
743 ;; predefined prefix keys, primarily as a mnemonic device. Nothing
744 ;; requires you to use the long key sequence `C-x j t f % *' to visit
745 ;; a file that has a given set of tags. It is expected that you will
746 ;; bind short key sequences to commands that you use often.
747 ;;
748 ;; The `C-x j' and `C-x 4 j' bindings are global. In addition, in
749 ;; some modes `j' is bound to the corresponding type-specific jump
750 ;; command. For example, in Info mode, `j' is bound to
751 ;; `bmkp-info-jump'. (Dired is an exception here: `J' is used
752 ;; instead of `j', since `j' is already taken for `dired-goto-file'.)
753 ;; These commands are also added to the mode's menu-bar menu.
754 ;;
755 ;; In Dired mode, `C-j' is bound to a special Dired-specific jump
756 ;; command, `bmkp-dired-this-dir-jump', whose destinations all use
757 ;; the current directory (`default-directory'). The aim of `C-j' is
758 ;; not to change directories but to change to a different set of
759 ;; Dired markings, switches, inserted subdirectories, or hidden
760 ;; subdirectories for the same Dired directory.
761 ;;
762 ;; In addition to the predefined bookmark types, which you can use as
763 ;; described above, you can define a "type"-specific jump command for
764 ;; any set of bookmarks. That is, you can use any specific set of
765 ;; bookmarks as the completion candidates for a new jump command.
766 ;; Such a set is really only a pseudo-type: the actual bookmarks can
767 ;; each be of any type.
768 ;;
769 ;; You could use this feature, for example, to define a jump command
770 ;; for the bookmarks that belong to a given project.
771 ;;
772 ;; One way to define such a command is to first mark the bookmarks
773 ;; that you want to be the completion candidates, then use `M-c'
774 ;; (command `bmkp-bmenu-define-jump-marked-command') in the bookmark
775 ;; list.
776 ;;
777 ;; The `*Bookmark List*' display defines a set of bookmarks, even
778 ;; without markings. So does each bookmark of type bookmark list,
779 ;; that is, a bookmark corresponding to a particular `*Bookmark
780 ;; List*' display state - see
781 ;; (@> "State-Restoring Commands and Bookmarks").
782 ;;
783 ;; You can capture the set of bookmarks corresponding to a `*Bookmark
784 ;; List*' display for use in navigation, that is, as the current
785 ;; "navigation list". Navigation here includes jumping and cycling
786 ;; - see (@> "Cycling, Navigation List").
787 ;;
788 ;; To capture in the navigation list the bookmarks corresponding to
789 ;; either the current `*Bookmark List*' display or a bookmark-list
790 ;; bookmark, use `C-x p B', which is bound to command
791 ;; `bmkp-choose-navlist-from-bookmark-list'. To then jump to a
792 ;; bookmark from such a navigation list, use `C-x j N' or `C-x 4 j N'
793 ;; (`bmkp-jump-in-navlist' or `bmkp-jump-in-navlist-other-window').
794
795 ;;(@* "Bookmark Tags")
796 ;; ** Bookmark Tags **
797 ;;
798 ;; With Bookmark+ you can bookmark many kinds of Emacs object.
799 ;; Bookmarks record locations - that is their primary purpose. They
800 ;; can also record annotations: general free-text descriptions of
801 ;; your choosing.
802 ;;
803 ;; Bookmark+ bookmarks can also be tagged, as a way to organize them,
804 ;; which also means as a way to organize the objects that are
805 ;; bookmarked.
806 ;;
807 ;; By "tagging" and "tag" in this context is meant associating
808 ;; keywords or other text with an object, typically in order to
809 ;; classify or characterize it. Tags are metadata about an object.
810 ;; This notion of tagging is sometimes called "delicious" tagging
811 ;; after the Web site www.delicious.com that popularized it
812 ;; (`http://en.wikipedia.org/wiki/Delicious_(website)').
813 ;;
814 ;; Be aware that there is another notion of "tag" associated with
815 ;; Emacs: that involving Emacs tags files, which record the locations
816 ;; of function, variable, etc. definitions in source files. There is
817 ;; no relation between the two notions of "tag".
818 ;;
819 ;; A bookmark tag is a string (or a cons whose car is a string - see
820 ;; (@> "Bookmark Tags Can Have Values")). You can add as many tags
821 ;; as you like to any bookmark, and multiple bookmarks can have the
822 ;; same tag(s). In fact, that's the whole idea behind using them for
823 ;; organizing.
824 ;;
825 ;; This feature is unrelated to the fact that bookmarks record
826 ;; locations and are useful for navigating. You can, if you want,
827 ;; use bookmarks to tag files in various ways purely for purposes of
828 ;; organizing them (e.g. into projects), whether or not you ever use
829 ;; the bookmarks as a way to visit them.
830 ;;
831 ;; For example, if you use Dired+ (library `dired+.el'), then you can
832 ;; use `M-b' (`diredp-do-bookmark') in Dired to create an autofile
833 ;; bookmark for each of the marked files in the Dired buffer. Even
834 ;; if you never use those bookmarks for navigating to the files, you
835 ;; can use them with tags to organize the files and thus operate on
836 ;; subsets of them.
837 ;;
838 ;; By default, you create bookmarks without tags and add tags to them
839 ;; later. If you prefer, you can customize option
840 ;; `bmkp-prompt-for-tags-flag' to non-nil so that you are prompted to
841 ;; add tags immediately whenever you set (create) a bookmark. There
842 ;; are also some commands, such as `bmkp-tag-a-file' (`C-x p t + a')
843 ;; and `bmkp-untag-a-file' (`C-x p t - a'), that always prompt for
844 ;; tags to add or remove. (In general, the key `a' is used in key
845 ;; sequences for autofile bookmarks.)
846 ;;
847 ;; When you are prompted to enter a tag, you type some text then hit
848 ;; `RET'. If you want to include a newline character in the tag
849 ;; itself, use `C-q C-j' (`C-j' is the newline character). You can
850 ;; use `C-q' this way to enter any character. If you do use complex
851 ;; strings as tags then you might prefer to simply edit a bookmark's
852 ;; tags in a separate buffer. You can do that using `C-x p t e' (or
853 ;; `T e' in the bookmark-list display).
854 ;;
855 ;; Whenever you are prompted for a tag you can use completion. The
856 ;; completion candidates available are the tag names defined by
857 ;; option `bmkp-tags-for-completion'. The default value of this
858 ;; option is `current', meaning use only the tags from the bookmarks
859 ;; in the current bookmark list as candidates. You can customize the
860 ;; option to include specific tags or the tags from bookmarks in
861 ;; specific bookmark files.
862 ;;
863 ;; You can use command `bmkp-list-all-tags' to list all of the tags
864 ;; defined by option `bmkp-tags-for-completion' or, with a numeric
865 ;; prefix argument, only the tags corresponding to the current
866 ;; bookmark file. You can list the tag names only or (using a
867 ;; non-negative prefix arg) show the full tag definitions, which
868 ;; include any associated tag values (see (@> "Bookmark Tags Can Have Values")
869 ;; for information about tag values).
870 ;;
871 ;; To make tags more useful, Bookmark+ provides *lots* of commands:
872 ;; commands for adding, removing, copying, pasting, and renaming
873 ;; tags; commands for jumping to bookmarks with particular sets of
874 ;; tags; and commands for marking or unmarking (in buffer `*Bookmark
875 ;; List*') bookmarks that are tagged in various ways.
876 ;;
877 ;; Most commands pertaining to tags are by default on prefix key `C-x
878 ;; p t' - use `C-x p t C-h' to see them. In buffer `*Bookmark
879 ;; List*', commands pertaining to tags are on prefix key `T' - use `T
880 ;; C-h' to see them.
881 ;;
882 ;; When combined with other Bookmark+ commands (e.g. search,
883 ;; query-replace) that apply to the marked bookmarks in the
884 ;; `*Bookmark List*' window, you can really do quite a lot using
885 ;; bookmark tags. Use your imagination!
886 ;;
887 ;; See Also:
888 ;;
889 ;; * (@> "Bookmark Records: What A Bookmark Looks Like")
890 ;; * (@> "Bookmarking the Marked Files in Dired")
891 ;; * (@> "Opening Bookmarks Using Windows File Associations")
892 ;; * (@> "Tag Commands and Keys")
893
894 ;;(@* "Bookmark Tags Can Have Values")
895 ;; ** Bookmark Tags Can Have Values **
896 ;;
897 ;; Bookmark tags are simply names (strings) when you create them.
898 ;; Nearly all of the predefined operations that use tags use these
899 ;; names: sorting, marking, jumping, and so on. But you can in fact
900 ;; add an associated value to any tag. This means that a tag can act
901 ;; just like an object attribute or property: it can be a name/value
902 ;; pair.
903 ;;
904 ;; To add a value to a tag that has none, or to change the current
905 ;; value of a tag, you use command `bmkp-set-tag-value', which is
906 ;; bound to `T v' in the bookmark list and bound to `C-x p t v'
907 ;; globally. You are prompted for the bookmark, the tag, and the new
908 ;; value.
909 ;;
910 ;; A tag value can be a number, symbol, string, list, vector, and so
911 ;; on. It can be as complex as you like. It can be any Emacs-Lisp
912 ;; object that has read syntax, that is, that is readable by the Lisp
913 ;; reader. (Everything that is saved as part of a bookmark must be
914 ;; readable; otherwise, your bookmark file could not be read
915 ;; (loaded).)
916 ;;
917 ;; Because tag values can be pretty much anything, you are pretty
918 ;; much on your own when it comes to making use of them. Bookmark+
919 ;; does not provide predefined functions for using tag values. In
920 ;; general, tag values are something you will use with home-grown
921 ;; Lisp code for your own purposes.
922 ;;
923 ;; However, you can easily make some interactive use of tag values
924 ;; with little effort. You can, for example, define a predicate that
925 ;; tests whether a bookmark has a tag value that satisfies some
926 ;; property (e.g. is a number greater than 3.14159265358979), and
927 ;; then you can use command `bmkp-bmenu-mark-bookmarks-satisfying' to
928 ;; mark those bookmarks.
929 ;;
930 ;; Tags that have the prefix "bmkp-" are reserved - do not name your
931 ;; own tags using this prefix.
932 ;;
933 ;; Currently, "bmkp-jump" is the only predefined bookmark tag. You
934 ;; can give this tag a value that is a function - it is called
935 ;; whenever the tagged bookmark is visited. Any Lisp-readable
936 ;; function value is allowed: a symbol or a lambda expression.
937 ;;
938 ;; For example, to display `Hello!' when a bookmark is visited you
939 ;; can use this:
940 ;;
941 ;; T v bookmark-jump RET (lambda () (message "Hello!"))
942 ;;
943 ;; The function that is the value of a "bmkp-jump" tag is called just
944 ;; after the the standard hook `bookmark-after-jump-hook' is invoked.
945 ;; You can use this tag to invoke functions that are specific to
946 ;; individual bookmarks; bookmarks can thus have their own, extra
947 ;; jump functions.
948
949 ;;(@* "Function, Sequence, and Variable-List Bookmarks")
950 ;; ** Function, Sequence, and Variable-List Bookmarks **
951 ;;
952 ;; Bookmarks are typically thought of only as recorded locations.
953 ;; Invoking a bookmark, called "jumping" to it, traditionally means
954 ;; just visiting its location. Bookmark+ looks at bookmarks in a
955 ;; more general way than that. A bookmark is a shortcut of some
956 ;; kind - nothing more.
957 ;;
958 ;; A given type of bookmark is defined by its handler function, which
959 ;; really could do anything you like. We've already seen the
960 ;; examples of region bookmarks, which restore the active region, and
961 ;; Dired bookmarks, which restore a set of Dired markings, switches,
962 ;; inserted subdirectories, and hidden (sub)directories.
963 ;;
964 ;; A "function bookmark" simply invokes some function - any function.
965 ;; You can, for instance, define a window or frame configuration and
966 ;; record that as a bookmark. Then jump to the bookmark to switch
967 ;; contexts. (You can also bookmark a desktop and jump to that.)
968 ;;
969 ;; Function bookmarks might not seem too interesting, since we have
970 ;; other ways of invoking functions in Emacs. But the other features
971 ;; of Bookmark+ combine with this feature. You can, for instance,
972 ;; tag such bookmarks.
973 ;;
974 ;; And you can combine them, invoking the functions sequentially.
975 ;; This is just a particular case of using a "sequence bookmark",
976 ;; which simply records a sequence of bookmarks. The bookmarks in a
977 ;; sequence can be of any kind, including other sequence bookmarks.
978 ;;
979 ;; Command `bmkp-make-function-bookmark' creates a function bookmark
980 ;; - you give it a function symbol or a lambda expression. Command
981 ;; `bmkp-bmenu-make-sequence-from-marked' creates a sequence from the
982 ;; marked bookmarks in the bookmark list, in their current order.
983 ;;
984 ;; A variable-list bookmark saves and restores the values of a set of
985 ;; variables. Command `bmkp-set-variable-list-bookmark' prompts you
986 ;; for the variables to include in the list and then sets the
987 ;; bookmark. Command `bmkp-jump-variable-list' (`C-x j v') restores
988 ;; the recorded variable values for the bookmark's buffer. You can
989 ;; also create variable-list bookmarks non-interactively, using
990 ;; function `bmkp-create-variable-list-bookmark'.
991 ;;
992 ;; If you use library `wide-n.el', then you can move among multiple
993 ;; restrictions (narrowings) in a buffer. The restrictions are
994 ;; stored in buffer-local variable `wide-n-restrictions'. Command
995 ;; `bmkp-set-restrictions-bookmark' bookmarks this value for the
996 ;; current buffer. Jumping to such a bookmark restores the saved
997 ;; ring/stack of restrictions.
998
999 ;;(@* "Editing Bookmarks")
1000 ;; ** Editing Bookmarks **
1001 ;;
1002 ;; In vanilla Emacs, you can edit the annotation associated with a
1003 ;; bookmark. And you can rename a bookmark. But that is all. There
1004 ;; is no easy way to really edit a bookmark.
1005 ;;
1006 ;; With Bookmark+:
1007 ;;
1008 ;; * You can use `r' in the bookmark-list display (or `C-x p r'
1009 ;; elsewhere) to edit the name and the target file name (bookmarked
1010 ;; location) of a bookmark. You are prompted for the new names.
1011 ;;
1012 ;; * You can use `e' in the bookmark-list display (or `C-x p E'
1013 ;; elsewhere) to edit a complete bookmark - all of its information.
1014 ;; You edit the internal Lisp sexp that represents the bookmark
1015 ;; record. This is the same internal definition that you see when
1016 ;; you use `C-u C-h RET' in the bookmark list.
1017 ;;
1018 ;; * You can use `E' in the bookmark-list display to edit the
1019 ;; bookmark records of all of the marked bookmarks. Again, this
1020 ;; means editing their internal Lisp sexps. In particular, this
1021 ;; gives you an easy way to edit tags across multiple bookmarks.
1022 ;; All of the editing power of Emacs is available.
1023 ;;
1024 ;; * You can use `T e' in the bookmark list (or `C-x p t e'
1025 ;; elsewhere), to edit a bookmark's tags.
1026 ;;
1027 ;; For all but the first of these, you are placed in a separate
1028 ;; editing buffer. Use `C-c C-c' when you are done editing, to save
1029 ;; your changes. (To cancel, just kill the buffer: `C-x k'.)
1030 ;;
1031 ;; There are many more keys and commands for editing bookmark tags.
1032 ;; You can copy tags (`C-x p t c') from one bookmark and paste them
1033 ;; to others, either replacing the original tags (`C-x p t C-y') or
1034 ;; adding to them (`C-x p t q'). You can be prompted for some tags
1035 ;; to add (`T +') or remove (`T -') from a bookmark. You can delete
1036 ;; a tag from all bookmarks (`T d'). You can rename a tag everywhere
1037 ;; (`T r'). And you can set a tag's value.
1038 ;;
1039 ;; As usual, all such commands are also available on the Bookmark+
1040 ;; menus. The menus provide quick reminders of the available keys,
1041 ;; as does the help from `?' in the bookmark-list display.
1042 ;;
1043 ;;(@* "Bookmark Records: What A Bookmark Looks Like")
1044 ;; *** Bookmark Records: What A Bookmark Looks Like ***
1045 ;;
1046 ;; It's worth dispelling some of the mystery about what a bookmark is
1047 ;; by mentioning what it looks like. This can help when you edit a
1048 ;; bookmark record. The first thing to mention is that the basic
1049 ;; structure of a bookmark record is described in the doc string of
1050 ;; variable `bookmark-alist' - but I'll repeat some of that info
1051 ;; here.
1052 ;;
1053 ;; A bookmark record is nothing more than a list whose first element
1054 ;; is a string, the bookmark name. The other list elements can be
1055 ;; thought of as attributes that define the bookmark: its data. Each
1056 ;; such attribute is a cons: a nonempty list or a dotted list.
1057 ;;
1058 ;; The car of the attribute is its name (a Lisp symbol). The cdr is
1059 ;; its value. What the value can be depends on the attribute - in
1060 ;; general it can be any Lisp value (number, string, list, symbol,
1061 ;; etc.). An attribute with a null cdr means the same thing as
1062 ;; having no such attribute present. For example, having the empty
1063 ;; attribute `(tags)' is the same as having to `tags' attribute at
1064 ;; all.
1065 ;;
1066 ;; There is nothing more to it: attributes can be anything you like,
1067 ;; provided you provide some code to recognize them and do something
1068 ;; with them.
1069 ;;
1070 ;; Of course, the types of attributes you use most (maybe always) are
1071 ;; predefined, and the vanilla `bookmark.el' code and the Bookmark+
1072 ;; code recognize and use them. The most important and most typical
1073 ;; attribute is this: `(filename . "/some/file/name.txt")', that is,
1074 ;; a cons whose car is the symbol `filename' and whose cdr is the
1075 ;; name (a string) of the bookmarked file.
1076 ;;
1077 ;; With that in mind, you can see that renaming a bookmark just means
1078 ;; changing the string that is its car. And relocating a bookmark
1079 ;; just means changing the string that is its `filename' - e.g., from
1080 ;; `(filename . "/home/foo.el")' to `(filename . "/some/other.xml")'.
1081 ;;
1082 ;; If you already have a bookmark file, typically `~/.emacs.bmk',
1083 ;; take a look at the bookmark records in it. A typical bookmark
1084 ;; also has these attributes, in addition to `filename': `position',
1085 ;; `front-context-string', and `rear-context-string'. You can guess
1086 ;; what they are - if not, see the doc string of `bookmark-alist'.
1087 ;;
1088 ;; A Bookmark+ bookmark typically has some additional attributes that
1089 ;; you can also guess. Attributes `time' and `visits' are updated
1090 ;; automatically each time you access the bookmark.
1091 ;;
1092 ;; Some bookmarks have a `handler' attribute whose value is a
1093 ;; function that "jumps" to the bookmark "location". I put those two
1094 ;; terms in quotes here because a handler is really just any function
1095 ;; - it can do anything you like, and there need not be any
1096 ;; associated location.
1097 ;;
1098 ;; Some Bookmark+ bookmarks, including autofile bookmarks, just
1099 ;; "jump" to a file. The position in the file is unimportant, and
1100 ;; "jumping" does not necessarily mean visiting the file with Emacs.
1101 ;; In effect, such bookmarks are just wrappers around the file,
1102 ;; letting you get the advantage of Bookmark+ features (tags etc.)
1103 ;; for a file. Such bookmarks, which you can create using `C-x p c
1104 ;; a' or `C-x p c f', contain a `file-handler' attribute instead of a
1105 ;; `handler' attribute. The difference between the two is that the
1106 ;; `file-handler' value is a function (Lisp function or shell
1107 ;; command) to be applied to the file, not to the bookmark.
1108 ;;
1109 ;; Remember: A bookmark is just a persistent bit of information,
1110 ;; typically meta-information about a file and a position in that
1111 ;; file.
1112 ;;
1113 ;; I'm mentioning all of this to make the point that you cannot
1114 ;; really hurt anything if you edit a bookmark record and you mess
1115 ;; things up. The worst you can do is mess up all of your bookmarks
1116 ;; by making the file unreadable as Lisp data. (It's always a good
1117 ;; idea to back up your bookmark file from time to time.)
1118 ;;
1119 ;; And if each bookmark record after you edit it is a cons with a
1120 ;; string car then your bookmarks are generally OK, even if you might
1121 ;; have ruined the details of one or two of them. Suppose you
1122 ;; somehow mistakenly delete the `a' in a `filename' attribute, for
1123 ;; instance. No big deal - that bookmark no longer has a
1124 ;; recognizable target location, but the other bookmarks are still
1125 ;; OK.
1126 ;;
1127 ;; The most important attribute for Bookmark+ users is probably
1128 ;; `tags'. Its value (the cdr) is a list of strings or conses - the
1129 ;; bookmark's tags. When you create a tag, it is typically a string
1130 ;; (just its name) - e.g. "blue". If you then give it a value as
1131 ;; well, it becomes a cons with that string (the name) as car and the
1132 ;; value as cdr - e.g. `("blue" . 42)' or `("blue" moonbeam 42)' -
1133 ;; here the cdr is the list `(moonbeam 42)'. Here is an example
1134 ;; `tags' attribute: `(tags "hegel" ("blue" . honeypot) "darwin")'.
1135 ;; Most of the time you will use strings as tags. See also
1136 ;; (@> "Bookmark Tags Can Have Values").
1137 ;;
1138 ;; When you edit bookmark records, just try to stay away from
1139 ;; changing any attributes that you are not familiar with. And make
1140 ;; sure that when you're done you have a proper Lisp list (open
1141 ;; parens closed etc.). If you've never played with Lisp before, do
1142 ;; not panic.
1143 ;;
1144 ;; Be aware if you see dots (`.') that they are important, and they
1145 ;; must be surrounded by whitespace: ` . '. The amount of whitespace
1146 ;; never matters in Lisp (except inside a string etc.).
1147 ;;
1148 ;; Such a dot just separates the car of a cons from its cdr. (What's
1149 ;; a cons? Just a car with a cdr!) If the cdr is a list then we
1150 ;; typically drop the dot and the list's parens: We write `(b)'
1151 ;; instead of `(b . ())' and `(a b)' instead of `(a . (b))' or `(a
1152 ;; . (b . ()))'.
1153
1154 ;;(@* "Bookmark-List Views - Saving and Restoring State")
1155 ;; ** Bookmark-List Views - Saving and Restoring State **
1156 ;;
1157 ;; The bookmark list (buffer `*Bookmark List*') provides a view into
1158 ;; the set of bookmarks. You can mark, sort, and hide (filter, omit)
1159 ;; bookmarks - see (@> "The Bookmark List Display"). The state of
1160 ;; the displayed bookmark list can thus change.
1161 ;;
1162 ;; At different times, and in different contexts, different views can
1163 ;; be useful. Bookmark+ lets you save the current state of the
1164 ;; displayed list and later restore it. There are a couple of
1165 ;; different ways to do this.
1166 ;;
1167 ;;
1168 ;;(@* "Quitting Saves the Bookmark-List State")
1169 ;; *** Quitting Saves the Bookmark-List State ***
1170 ;;
1171 ;; If option `bmkp-bmenu-state-file' is non-nil, which it is by
1172 ;; default, then Bookmark+ remembers the last state of the bookmark
1173 ;; list when you quit it or you quit Emacs, and it restores that
1174 ;; state when you show the list again (which could be in the next
1175 ;; Emacs session). You can think of this feature as your "Home" page
1176 ;; for bookmarks, giving you a stepping stone to the files and
1177 ;; directories you use most.
1178 ;;
1179 ;; If, for example, when you quit the bookmark list you are showing
1180 ;; only bookmarks to Info nodes and UNIX manual pages, sorted in a
1181 ;; particular way, and with some of them marked with `>' for
1182 ;; particular processing, then the next time you open the list the
1183 ;; same state is restored: the same set of bookmarks is shown, in the
1184 ;; same order, with the same markings. Deletion flags (`D') and
1185 ;; modification indicators (`*') are purposefully not saved as part
1186 ;; of the display state - they are lost when you quit the display.
1187 ;;
1188 ;; You can turn off this automatic bookmark-list display state
1189 ;; saving, if you want, by customizing option `bmkp-bmenu-state-file'
1190 ;; to nil. And you can toggle this option at any time, using `C-M-~'
1191 ;; in the bookmark list (command
1192 ;; `bmkp-toggle-saving-menu-list-state'). In particular, if you want
1193 ;; your next visit to the bookmark list to start out with a
1194 ;; previously recorded state instead of the current state, just hit
1195 ;; `C-M-~' before quitting the bookmark list.
1196 ;;
1197 ;;
1198 ;;(@* "State-Restoring Commands and Bookmarks")
1199 ;; *** State-Restoring Commands and Bookmarks ***
1200 ;;
1201 ;; In addition to automatically saving/restoring the final
1202 ;; bookmark-list display state, you can save this state at any time,
1203 ;; any number of times, for later restoration. This gives you the
1204 ;; ability to create multiple persistent views of your bookmarks.
1205 ;;
1206 ;; There are two ways to do this:
1207 ;;
1208 ;; * Create a bookmark for the `*Bookmark List*' buffer itself: a
1209 ;; bookmark-list bookmark.
1210 ;;
1211 ;; * Define a command that restores the bookmark-list state.
1212 ;;
1213 ;; When you use `C-x r m' (`bookmark-set') in buffer `*Bookmark
1214 ;; List*' to create a bookmark-list bookmark, the current sort order,
1215 ;; filter, regexp pattern, title, and omit list are saved as part of
1216 ;; the bookmark. (These concepts are described below - see
1217 ;; (@> "Bookmark List Display").) Jumping to such a bookmark
1218 ;; restores all of these.
1219 ;;
1220 ;; Alternatively, you can define a command that does the same thing,
1221 ;; but without creating another bookmark - use `c'
1222 ;; (`bmkp-bmenu-define-command') in the bookmark list to do this.
1223 ;; You are prompted for the name of the new command. Use the command
1224 ;; anytime (including in another Emacs session) to restore the
1225 ;; bookmark list.
1226 ;;
1227 ;; Define any number of such commands for the views you use. The
1228 ;; file for saving the definitions (see option
1229 ;; `bmkp-bmenu-commands-file') is never overwritten, so you can also
1230 ;; add other code to it manually, if you want. The file is read the
1231 ;; first time the bookmark list is displayed in a given Emacs
1232 ;; session.
1233 ;;
1234 ;; The state that is saved and restored using a bookmark-list
1235 ;; bookmark or a command defined using `c' is only a partial state.
1236 ;; The current set of markings and some other information are not
1237 ;; saved, in order to save disk space and save/restore time.
1238 ;;
1239 ;; Sometimes, however, you really want to save the entire
1240 ;; bookmark-list state, creating a full snapshot. You can use `C'
1241 ;; (`bmkp-bmenu-define-full-snapshot-command') to do that. This
1242 ;; defines a command that restores the bookmark list completely.
1243 ;; That is the same thing that happens automatically (by default)
1244 ;; whenever you quit the bookmark list (or Emacs), but defining
1245 ;; snapshot commands lets you have multiple saved states and switch
1246 ;; to them at will.
1247 ;;
1248 ;; Be aware, however, that full-snapshot command definitions can be
1249 ;; quite large, since they each contain a copy of the current
1250 ;; bookmark list and any accessory lists (hidden and marked bookmarks
1251 ;; etc.).
1252 ;;
1253 ;; Whether you use `c' or `C' to define a state-restoring command or
1254 ;; you create a bookmark-list bookmark, you can create a sequence
1255 ;; bookmark that combines such bookmark-list restoration with
1256 ;; activation of other bookmarks. (To include a state-restoring
1257 ;; command in a sequence, you need to first create a function
1258 ;; bookmark that uses the command, and then include that bookmark in
1259 ;; the sequence.)
1260
1261 ;;(@* "Bookmarking without Visiting the Target")
1262 ;; ** Bookmarking without Visiting the Target **
1263 ;;
1264 ;; There are several use cases for bookmarking a target without
1265 ;; visiting it:
1266 ;;
1267 ;; 1. In an Emacs buffer you come across a reference or a link to a
1268 ;; file or a URL. You bookmark the target without bothering to
1269 ;; visit it first. You do not really care which position in the
1270 ;; file is bookmarked.
1271 ;;
1272 ;; 2. In Dired, you mark certain files and then bookmark all (each)
1273 ;; of them, in one operation.
1274 ;;
1275 ;; 3. In a compilation buffer (e.g. `*grep*', `*compile*') or an
1276 ;; occur or multi-occur buffer (`*Occur*'), you bookmark one or
1277 ;; more of the hits. Such a bookmark takes you to the appropriate
1278 ;; position in the target file or buffer.
1279 ;;
1280 ;; 4. You bookmark a file that you might not even be able to visit in
1281 ;; Emacs (in the sense of editing it in a buffer) - for example, a
1282 ;; music file. "Jumping" to the bookmark performs an operation
1283 ;; appropriate to the file - for example, playing music.
1284 ;;
1285 ;;
1286 ;;(@* "Bookmarking a File or a URL")
1287 ;; *** Bookmarking a File or a URL ***
1288 ;;
1289 ;; You can use commands `bmkp-file-target-set' and
1290 ;; `bmkp-url-target-set', bound by default to `C-x p c f' and `C-x p
1291 ;; c u', to bookmark any file or URL. Completion is available, the
1292 ;; default file name or URL being determined by the text at point.
1293 ;; In addition to the file or URL, you are prompted for the bookmark
1294 ;; name. (In general, the keys `f' and `u' are used in key sequences
1295 ;; for file and URL bookmarks, respectively.)
1296 ;;
1297 ;;
1298 ;;(@* "Bookmarking the Marked Files in Dired")
1299 ;; *** Bookmarking the Marked Files in Dired ***
1300 ;;
1301 ;; If you use Dired+ (library `dired+.el'), then you can bookmark all
1302 ;; of the marked files in a Dired buffer at once, as autofiles, even
1303 ;; if you normally do not or cannot visit those files in Emacs.
1304 ;; These keys are available in Dired:
1305 ;;
1306 ;; `M-b' - Bookmark each marked file
1307 ;; `C-M-S-b' (aka `C-M-B') - Bookmark each marked file in a
1308 ;; bookmark-file that you specify
1309 ;; `C-M-b' - Bookmark each marked file in a
1310 ;; bookmark-file you specify, and create
1311 ;; a bookmark for that bookmark-file
1312 ;;
1313 ;; Each of these commands bookmarks each of the marked files as an
1314 ;; autofile. By default, the bookmark file used for the latter two
1315 ;; commands is in the current directory.
1316 ;;
1317 ;; If you use multiple `C-u' as a prefix arg for these commands, then
1318 ;; you can bookmark all of the files in Dired, regardless of
1319 ;; markings, as follows:
1320 ;;
1321 ;; `C-u C-u' - Use all files in Dired, except directories
1322 ;; `C-u C-u C-u' - Use all files and dirs, except `.' and `..'
1323 ;; `C-u C-u C-u C-u' - Use all files and all directories
1324 ;;
1325 ;; `C-M-b' not only bookmarks each of the marked files, it also
1326 ;; creates a bookmark-file bookmark for that set of bookmarks. See
1327 ;; (@> "Bookmark-File Bookmarks"), below.
1328 ;;
1329 ;; You can later "jump" to that bookmark to load its set of
1330 ;; bookmarks. If you use `C-u' when you jump to it, then you switch
1331 ;; bookmark files, so that `C-x p e' (or `C-x r l') displays only the
1332 ;; bookmarks created from the marked files. Without `C-u', jumping
1333 ;; to the bookmark-file bookmark simply loads its bookmarks into the
1334 ;; current set of bookmarks.
1335 ;;
1336 ;;
1337 ;;(@* "Bookmarking Compilation, Grep, and Occur Hits")
1338 ;; *** Bookmarking Compilation, Grep, and Occur Hits ***
1339 ;;
1340 ;; In a similar way, you can bookmark the file or buffer positions of
1341 ;; selected hits in a compilation buffer (including `*grep*') or an
1342 ;; `occur' or `multi-occur' buffer.
1343 ;;
1344 ;; `C-c C-b' in such a buffer bookmarks the target of the hit at
1345 ;; point. `C-c C-M-b' bookmarks the target of each hit in the
1346 ;; buffer.
1347 ;;
1348 ;; `C-c C-M-b' in these buffers is thus similar to `M-b' in a Dired
1349 ;; buffer. Unlike Dired, however, there is no way to mark such hits.
1350 ;; Every hit is bookmarked.
1351 ;;
1352 ;; Nevertheless, you can get the same effect. Just use `C-x C-q' to
1353 ;; make the buffer writable (e.g. temporarily), and then remove any
1354 ;; hits that you do not want to bookmark. You can remove hits anyway
1355 ;; you like, including by `C-k' and by regexp (`M-x flush-lines' or
1356 ;; `M-x keep-lines').
1357 ;;
1358 ;; See also: (@> "Autonamed Bookmarks - Easy Come Easy Go"),
1359 ;; bookmarking occur hits using autonamed bookmarks.
1360 ;;
1361 ;;
1362 ;;(@* "Bookmarking Files That You Cannot Visit with Emacs")
1363 ;; *** Bookmarking Files That You Cannot Visit with Emacs ***
1364 ;;
1365 ;; You use lots of files that you never visit using Emacs, but that
1366 ;; you might like to keep track of or access in other ways: music
1367 ;; files, image files, whatever.
1368 ;;
1369 ;; You can define a new kind of bookmark for any file type you are
1370 ;; interested in, implementing a bookmark handler for it that
1371 ;; performs the appropriate action on it when you "jump" to it. That
1372 ;; action needs to be expressible using an Emacs function, but it
1373 ;; need not have anything to do with visiting the file in Emacs.
1374 ;;
1375 ;; When you bookmark a target file that Emacs recognizes as an image
1376 ;; or sound file, an appropriate handler is used automatically.
1377 ;;
1378 ;; After you create individual bookmarks for, say, music or image
1379 ;; files, you can use `P B' in the bookmark-list display to show only
1380 ;; those bookmarks, and then use `C-x r m' to bookmark that state of
1381 ;; the bookmark-list.
1382 ;;
1383 ;; That bookmark-list bookmark in effect becomes a music playlist or
1384 ;; an image library or slideshow. Jump to it anytime you want to
1385 ;; listen to that set of music pieces or view those images. And you
1386 ;; can use `C-x p B' and then `C-x p next' to cycle among the music
1387 ;; pieces or images (slideshow). (See (@> "Cycling the Navigation List").)
1388 ;;
1389 ;; Together with the use of bookmark tags, this gives you a handy way
1390 ;; to organize and access objects of any kind. See (@> "Bookmark Tags").
1391 ;;
1392 ;; You use option `bmkp-default-handlers-for-file-types' to control
1393 ;; which operation (handler) to use for which file type. This is a
1394 ;; set of associations (an alist) with each key being a regexp
1395 ;; matching a file name, and with each associated value being a Lisp
1396 ;; sexp that evaluates to either a shell command (a string) or an
1397 ;; Emacs function (a symbol or lambda form).
1398 ;;
1399 ;; You can think of `bmkp-default-handlers-for-file-types' as
1400 ;; somewhat analogous to `auto-mode-alist'. But it maps file-name
1401 ;; patterns to file actions instead of mapping them to buffer modes.
1402 ;; And it has an effect only when you use certain commands.
1403 ;;
1404 ;; The handler for the bookmark created invokes the shell command or
1405 ;; the Emacs function with the file name as argument.
1406 ;;
1407 ;; Here is an example option value:
1408 ;;
1409 ;; (("\\.ps$" . "gsview32.exe")
1410 ;; ("\\.html?$" . browse-url)
1411 ;; ("\\.doc$" . w32-browser))
1412 ;;
1413 ;; This value causes creation of bookmarks that, when you jump to
1414 ;; them, invoke:
1415 ;;
1416 ;; * shell command `gsview32.exe' on the bookmark's
1417 ;; target file if it is PostScript (extension `.ps')
1418 ;;
1419 ;; * Emacs Lisp function `browse-url' on the file if it is HTML
1420 ;; (extension `.htm' or `.html')
1421 ;;
1422 ;; * Emacs Lisp function `w32-browser' on the file if the file
1423 ;; extension is `.doc' (e.g., a Microsoft Word file)
1424 ;;
1425 ;; The default value of `bmkp-default-handlers-for-file-types' is
1426 ;; taken from the value of option `dired-guess-shell-alist-user'
1427 ;; (from Dired X).
1428 ;;
1429 ;; The associations are checked in order, and the first one that
1430 ;; matches the given file name is used. You can thus order them to
1431 ;; deal with overlapping file-name patterns.
1432 ;;
1433 ;; If no matching file association is found in
1434 ;; `bmkp-default-handlers-for-file-types', and if option
1435 ;; `bmkp-guess-default-handler-for-file-flag' is non-nil (it is nil
1436 ;; by default), then Bookmark+ will guess a shell command to use. It
1437 ;; does this by matching the file name against
1438 ;; `dired-guess-shell-alist-default' (also from Dired X). In Emacs
1439 ;; 23+, if it finds no shell command that way then it guesses one
1440 ;; based on mailcap entries.
1441 ;;
1442 ;; When a bookmark is created using `C-x p c f' or `C-x p c a' for a
1443 ;; file that matches `bmkp-default-handlers-for-file-types', the
1444 ;; shell command or Lisp function that "jumps to" (opens) the file is
1445 ;; saved in the bookmark as attribute `file-handler' (not `handler').
1446 ;;
1447 ;;
1448 ;;(@* "Opening Bookmarks Using Windows File Associations")
1449 ;; *** Opening Bookmarks Using Windows File Associations ***
1450 ;;
1451 ;; If you use Microsoft Windows there is no need to define new
1452 ;; bookmark types and handlers, if the action you want is the one
1453 ;; that Windows associates with the file. You already have a set of
1454 ;; file/program associations, and Bookmark+ recognizes these as
1455 ;; alternative handlers.
1456 ;;
1457 ;; You can thus take advantage of Windows file associations to open
1458 ;; bookmarks for files of all kinds. To do this, you also need
1459 ;; library `w32-browser.el'. In the bookmark list, the following
1460 ;; keys are bound to commands that open bookmarks using the
1461 ;; associated Windows `Open' applications:
1462 ;;
1463 ;; `M-RET' - `bmkp-bmenu-w32-open'
1464 ;; `M-mouse-2' - `bmkp-bmenu-w32-open-with-mouse'
1465 ;; `M-o' - `bmkp-bmenu-w32-open-select'
1466 ;;
1467 ;; Windows file associations are always available to you, in addition
1468 ;; to any other file associations that you define using
1469 ;; `bmkp-default-handlers-for-file-types' (see
1470 ;; (@> "Bookmarking Files That You Cannot Visit with Emacs")).
1471 ;;
1472 ;; You can thus have two different programs associated with the same
1473 ;; kind of file. Your MS Windows file association for PostScript
1474 ;; might, for example, use Adobe Distiller to create a PDF file from
1475 ;; PostScript, while your `bmkp-default-handlers-for-file-types'
1476 ;; association for PostScript might use GhostView to display it
1477 ;; directly.
1478 ;;
1479 ;; Besides using `M-RET' etc. in buffer `*Bookmark List*', if in
1480 ;; `bmkp-default-handlers-for-file-types' you register `w32-browser'
1481 ;; as the association to use for a given file pattern, then you can
1482 ;; use command `bmkp-w32-browser-jump' (not bound, by default)
1483 ;; anywhere to open a bookmark whose file name matches that pattern,
1484 ;; using its Windows file-association program.
1485 ;;
1486 ;; You can also specify `w32-browser' as the bookmark "type" when you
1487 ;; use command `bmkp-jump-to-type' (`C-x j :'). Either of these
1488 ;; approaches gives you a way to use completion to choose a bookmark
1489 ;; to open using a Windows file association.
1490 ;;
1491 ;; Specifying such an association in
1492 ;; `bmkp-default-handlers-for-file-types' means that bookmarks for
1493 ;; such a file will have a `file-handler' value of `w32-browser', to
1494 ;; "jump" to (i.e., open) the file.
1495 ;;
1496 ;; To set up a given file extension for use this way, add an entry
1497 ;; (REGEXP . w32-browser) to option
1498 ;; `bmkp-default-handlers-for-file-types', where REGEXP matches the
1499 ;; file extension.
1500 ;;
1501 ;; For example, to make a command such as `bmkp-bookmark-a-file'
1502 ;; (`C-x p c a') automatically bookmark `*.doc' files using the
1503 ;; associated MS Windows program (typically MS Word), add this entry:
1504 ;; ("\\.doc$" . w32-browser).
1505 ;;
1506 ;;
1507 ;;(@* "Autofile Bookmarks")
1508 ;; *** Autofile Bookmarks ***
1509 ;;
1510 ;; An autofile bookmark, or just autofile, is a bookmark that uses
1511 ;; the non-directory part of its file name as its bookmark name.
1512 ;;
1513 ;; You can look at an autofile bookmark as just a file wrapper: a way
1514 ;; to attach meta information (such as tags) to a file. But you can
1515 ;; use an autofile bookmark much as you would use a file.
1516 ;;
1517 ;; To create a new autofile bookmark, you can use
1518 ;; `bmkp-bookmark-a-file' (aka `bmkp-autofile-set'), which is bound
1519 ;; by default to `C-x p c a'. (In general, the key `a' is used in
1520 ;; key sequences for autofile bookmarks.)
1521 ;;
1522 ;; If user option `bmkp-propertize-bookmark-names-flag' is non-nil,
1523 ;; which it is by default with Emacs 21 and later, then you can have
1524 ;; multiple bookmarks with the same name. This is important for
1525 ;; autofile bookmarks because the bookmark name is only the
1526 ;; non-directory part of the file name. This Bookmark+ feature lets
1527 ;; you have different autofile bookmarks for files of the same name
1528 ;; in different directories.
1529 ;;
1530 ;; In addition to the single autofile bookmark that you can create
1531 ;; for a given absolute file location, you can of course create
1532 ;; additional bookmarks to the same file, using different bookmark
1533 ;; names. Among other things, this lets you tag the same file in
1534 ;; different ways.
1535 ;;
1536 ;; You can use `C-x j a' (`bmkp-autofile-jump') or `C-x 4 j a'
1537 ;; (`bmkp-autofile-jump-other-window') to visit an autofile bookmark.
1538 ;; And there are commands for visiting an autofile that is tagged in
1539 ;; certain ways. For example, `bmkp-autofile-some-tags-regexp-jump'
1540 ;; (`C-x j t a % +') jumps to an autofile bookmark that has at least
1541 ;; one tag matching a given regexp. See (@> "Tagging Files").
1542 ;;
1543 ;;
1544 ;;(@* "A Type-Aware `find-file'")
1545 ;; *** A Type-Aware `find-file' ***
1546 ;;
1547 ;; User option `bmkp-default-handlers-for-file-types' (see
1548 ;; (@> "Bookmarking Files That You Cannot Visit with Emacs")) gives
1549 ;; you a way to associate a file type, as determined by the file
1550 ;; name (typically its extension) with a default file action. This
1551 ;; is like MS Windows file associations, but it is specific to Emacs
1552 ;; and Bookmark+. And it is useful for more than just bookmarks.
1553 ;;
1554 ;; Commands `bmkp-find-file' (`C-x j C-f') and
1555 ;; `bmkp-find-file-other-window' (`C-x 4 j C-f') take advantage of
1556 ;; this association to open files. If a file name matches no pattern
1557 ;; in `bmkp-default-handlers-for-file-types' then these commands act
1558 ;; like `find-file' and `find-file-other-window'. Otherwise, the
1559 ;; invoke the associated file handler in
1560 ;; `bmkp-default-handlers-for-file-types'.
1561 ;;
1562 ;; Invoking the handler is just what the ordinary autofile jump
1563 ;; commands (e.g. `C-x j a') do. But `bmkp-find-file' is different
1564 ;; in a couple of ways.
1565 ;;
1566 ;; Like vanilla `find-file' (`C-x C-f'), `C-x j C-f' and `C-x 4 j
1567 ;; C-f' use `read-file-name' to prompt you for the file name. The
1568 ;; completion candidates are the names of all of the files in the
1569 ;; current directory (`default-directory'), that is, the directory of
1570 ;; your current minibuffer input. This includes the names of any
1571 ;; autofile bookmarks in the same directory. And like `C-x C-f' you
1572 ;; can change directory, navigating up and down the file hierarchy.
1573 ;; In sum, these commands are file-aware.
1574 ;;
1575 ;; The ordinary autofile jump commands on the other hand use
1576 ;; `completing-read' to complete your input against all autofile
1577 ;; bookmark names, regardless of directory. And since the bookmark
1578 ;; names reflect only the relative file names, it is not so easy to
1579 ;; distinguish two autofiles with the same name but in different
1580 ;; directories. (Icicles can help here, BTW.)
1581 ;;
1582 ;; There is a `bmkp-find-file-' command that corresponds to each
1583 ;; `bmkp-autofile-' command. For example,
1584 ;; `bmkp-find-file-some-tags-regexp' (`C-x j t C-f % +') corresponds
1585 ;; to `bmkp-autofile-some-tags-regexp-jump' (`C-x j t a % +'). All
1586 ;; `bmkp-find-file' commands use `C-f' in their key bindings, as a
1587 ;; reminder of their reading file names a la `find-file'.
1588 ;;
1589 ;; But whereas `C-x j C-f' and `C-x 4 j C-f' let you access any file,
1590 ;; the other `bmkp-find-file-' commands, which find files that have
1591 ;; certain tags, provide only autofiles as completion candidates.
1592 ;; That's obvious, since files are tagged by bookmarking them.
1593 ;;
1594 ;; You can thus use the `C-f' commands to take advantage of
1595 ;; file-action associations that you define. But if you want to
1596 ;; associate metadata (e.g. tags) with files, then you will want to
1597 ;; create autofiles. You can do this when you invoke these commands,
1598 ;; by providing a prefix argument. Thus, for example, `C-u C-x j C-f
1599 ;; foo.doc' opens file `foo.doc', respecting any handler recorded for
1600 ;; it via option `bmkp-default-handlers-for-file-types' - but it also
1601 ;; creates an autofile bookmark for it.
1602 ;;
1603 ;; Whenever an autofile bookmark is used, regardless of whether you
1604 ;; access it using a `bmkp-autofile*' command or a `bmkp-find-file*'
1605 ;; command, the full bookmark record (including handler) is taken
1606 ;; into account.
1607 ;;
1608 ;; Note, however, that the `C-f' tag commands differ from the `a' tag
1609 ;; commands in how the completion candidates are filtered.
1610 ;;
1611 ;; For the former, `read-file-name' is passed a predicate that is
1612 ;; applied to each file name in the directory, filtering out any such
1613 ;; candidates that do not satisfy it (e.g., do not have the required
1614 ;; tags).
1615 ;;
1616 ;; This happens before you type any input to match the file name.
1617 ;; The predicate checks for a corresponding autofile and checks its
1618 ;; tags (depending on the command). If there are lots of files in
1619 ;; the current directory, this can take a while.
1620 ;;
1621 ;; For the latter, similar tests are made, but instead of testing
1622 ;; each file in the current directory, these commands test each
1623 ;; bookmark in the current bookmark list. If there are lots of
1624 ;; bookmarks this can take a while.
1625 ;;
1626 ;; In some cases a `C-f' command is quicker; in some cases a `a'
1627 ;; command is quicker.
1628 ;;
1629 ;; If you use Icicles, then the performance hit for `C-f' when there
1630 ;; are lots of files in a directory is greatly reduced. This is
1631 ;; because Icicles applies the filtering predicate after, not before,
1632 ;; you type text in the minibuffer. In other words, instead of
1633 ;; testing each file in the directory, it tests only the files that
1634 ;; match your input. (In addition, if you use Icicles then you get
1635 ;; multi-command versions of each of these bookmark commands, which
1636 ;; means that you can visit more than one file per command
1637 ;; invocation.)
1638
1639 ;;(@* "Tagging Files")
1640 ;; ** Tagging Files **
1641 ;;
1642 ;; Section (@> "Tags: Sets of Bookmarks") covers bookmark tags, which
1643 ;; are persistent metadata that you define to help you organize
1644 ;; bookmarks into meaningful sets.
1645 ;;
1646 ;; Section (@> "Autofile Bookmarks") describes autofile bookmarks,
1647 ;; which, in effect, let you treat files generally as if they were
1648 ;; bookmarks. You can choose a file to visit or act on by its name
1649 ;; and location, but also by its bookmark metadata.
1650 ;;
1651 ;; In particular, you can tag a file - that is, specify tags for its
1652 ;; associated autofile bookmark. And you can then visit a file that
1653 ;; has a given set of tags. Bookmark+ provides file commands that
1654 ;; automatically create and manipulate autofile bookmarks, that is,
1655 ;; bookmarks that have the same name as the files they tag.
1656 ;;
1657 ;; Command `bmkp-tag-a-file' (aka `bmkp-autofile-add-tags'), bound by
1658 ;; default to `C-x p t + a', prompts you for a set of tags and a file
1659 ;; location, and creates or sets the corresponding autofile bookmark.
1660 ;; Command `bmkp-untag-a-file' (aka `bmkp-autofile-remove-tags'),
1661 ;; bound by default to `C-x p t - a', similarly lets you remove
1662 ;; specified tags from a file.
1663 ;;
1664 ;; If you also use library Icicles, then you can act on multiple
1665 ;; files during the same command (a "multi-command"). You can thus
1666 ;; all at once tag a set of files the same way, or act on a set of
1667 ;; files that are tagged similarly. Icicles also lets you create
1668 ;; autofiles or add or remove tags, on the fly, whenever you use
1669 ;; commands (e.g. `C-x C-f') that access files.
1670 ;;
1671 ;; If you also use library Dired+ (`dired+.el') then you can use
1672 ;; `C-+' to add tags to the marked files and `C--' to remove tags
1673 ;; from them. You can use `C-M-+' and `C-M--' to do the same thing
1674 ;; for the current file. You can also use items from the Dired menus
1675 ;; to do these things.
1676 ;;
1677 ;; Bookmark+ provides two kinds of command for visiting files
1678 ;; associated with bookmarks that have tags.
1679 ;;
1680 ;; The first kind uses bookmarks directly: you choose a bookmark
1681 ;; name, not a file name, but the candidates are only file and
1682 ;; directory bookmarks. These commands have the prefix `bmkp-file-'
1683 ;; or `bmkp-autofile-'.
1684 ;;
1685 ;; As a special case, commands with the prefix `bmkp-file-this-dir-'
1686 ;; limit the choices to bookmarks for files and subdirectories of the
1687 ;; current directory. By default, the commands across all
1688 ;; directories are on prefix key `C-x j t f', and those for the
1689 ;; current directory only are on prefix key `C-x j t .'. See
1690 ;; (@> "Different Types of Jump Commands") for more about these
1691 ;; commands.
1692 ;;
1693 ;; The second kind of command is for visiting tagged files, that is,
1694 ;; autofile bookmarks, just like the commands with prefix
1695 ;; `bmkp-autofile-'. However, these commands do not handle the
1696 ;; bookmark as such, but only its file name. They recognize its
1697 ;; tags, but they pay no attention to any special handler or other
1698 ;; recorded information.
1699 ;;
1700 ;; These commands have the prefix `bmkp-find-file-', and they are on
1701 ;; the prefix key `C-x j t C-f'. The `C-f' here is intended to
1702 ;; remind you of command `find-file' (`C-x C-f'). Like `find-file',
1703 ;; they use `read-file-name' to read the bookmark's file name,
1704 ;; instead of using `completing-read' to read the bookmark name.
1705 ;;
1706 ;; Yes, for an autofile bookmark the bookmark name and the (relative)
1707 ;; file name are the same. But `read-file-name' is file-aware, and
1708 ;; lets you browse up and down the directory hierarchy.
1709 ;;
1710 ;; The `bmkp-find-file-' commands are available only for Emacs 22 and
1711 ;; later (because they use `read-file-name' with a PREDICATE
1712 ;; argument).
1713 ;;
1714 ;; For example:
1715 ;;
1716 ;; `C-x j t f % +' is `bmkp-file-some-tags-regexp-jump'
1717 ;; `C-x j t . % +' is `bmkp-file-this-dir-some-tags-regexp-jump'
1718 ;; `C-x j t a % +' is `bmkp-autofile-some-tags-regexp-jump'
1719 ;; `C-x j t C-f % +' is `bmkp-find-file-some-tags-regexp'
1720 ;;
1721 ;; * The first of these visits any file bookmark that has at least
1722 ;; one tag among the tags you specify, and you choose among
1723 ;; bookmark names. The files can be in any directories.
1724 ;;
1725 ;; * The second is similar to the first, but only bookmarks for files
1726 ;; in the current directory are completion candidates.
1727 ;;
1728 ;; * The third is similar to the first, but only autofile bookmarks
1729 ;; are completion candidates.
1730 ;;
1731 ;; * The fourth is similar to the third regarding tags, but it uses
1732 ;; `read-file-name', so you can browse up and down the file
1733 ;; hierarchy. The completion candidates are file names, not
1734 ;; bookmark names.
1735 ;;
1736 ;; If you use Icicles, there are similar sets of commands, but they
1737 ;; all let you act on multiple files at the same time
1738 ;; (multi-commands). For example, you can delete (or byte-compile
1739 ;; or...) a set of files according to their tags.
1740 ;;
1741 ;; Remember that you can create multiple bookmarks for the same file,
1742 ;; providing them with different sets of tags. (Only one of the
1743 ;; bookmarks is the autofile bookmark.)
1744 ;;
1745 ;; You can also use multiple bookmark files (the files that record
1746 ;; bookmarks). Different projects can thus have different tags for
1747 ;; the same sets of files, even using just autofile bookmarks. See
1748 ;; (@> "Using Multiple Bookmark Files").
1749 ;;
1750 ;; A file bookmark can have any number of tags, and multiple file
1751 ;; bookmarks can have the same tag. You can sort, show/hide, or mark
1752 ;; files based on their tags.
1753
1754 ;;(@* "Using Multiple Bookmark Files")
1755 ;; ** Using Multiple Bookmark Files **
1756 ;;
1757 ;; Bookmark-list views (see
1758 ;; (@> "Bookmark-List Views - Saving and Restoring State")) provide
1759 ;; one way to switch among various sets of bookmarks that you use.
1760 ;; But that feature affects only the bookmarks that you see displayed
1761 ;; in buffer `*Bookmark List*', not the actual set of available
1762 ;; bookmarks.
1763 ;;
1764 ;; The bookmarks available to you are defined in a bookmark file. By
1765 ;; default, they are stored in the file named by option
1766 ;; `bmkp-last-as-first-bookmark-file', if non-`nil', otherwise in the
1767 ;; file named by option `bookmark-default-file' (`~/.emacs.bmk', by
1768 ;; default).
1769 ;;
1770 ;; If you use only one bookmark file then you never need to load or
1771 ;; save it manually. Emacs does that for you automatically.
1772 ;;
1773 ;; But you can have multiple bookmark files if you want, and at any
1774 ;; time you can change the bookmark file that is current. To do
1775 ;; that, use `C-x p L' (or just `L' in the bookmark-list display),
1776 ;; which is bound to command `bmkp-switch-bookmark-file-create'.
1777 ;; Having multiple bookmark files gives you an added degree of
1778 ;; flexibility.
1779 ;;
1780 ;; By default, the last bookmark file you used, in your last Emacs
1781 ;; session, is the initial bookmark file that is loaded automatically
1782 ;; in your next session. But if you prefer, you can make Bookmark+
1783 ;; always start with the same bookmark file
1784 ;; (`bookmark-default-file'). User option
1785 ;; `bmkp-last-as-first-bookmark-file' controls this.
1786 ;;
1787 ;; You can easily see which bookmark file is current at any time: It
1788 ;; is shown at the top of buffer `*Bookmark List*', and it is near
1789 ;; the top of the help output from command
1790 ;; `bmkp-bmenu-mode-status-help', which is what is bound to `?' and
1791 ;; `C-h m' in buffer `*Bookmark List*'.
1792 ;;
1793 ;; When you switch to another bookmark file, the default choice for
1794 ;; the file to switch to is the last bookmark file you used (in the
1795 ;; same session). So it is trivial to toggle back and forth between
1796 ;; two bookmark files: just hit `RET' to accept the default.
1797 ;;
1798 ;; When bookmarks are saved automatically, or when you save them
1799 ;; using `bookmark-save' (`S' in the bookmark-list display or `C-x p
1800 ;; s' globally) and you don't use a prefix argument, they are saved
1801 ;; in the current bookmark file.
1802 ;;
1803 ;; You can turn off the automatic saving of the current bookmark
1804 ;; file, by customizing option `bookmark-save-flag' to nil. And you
1805 ;; can toggle this option at any time, using `M-~' in the bookmark
1806 ;; list (command `bmkp-toggle-saving-bookmark-file').
1807 ;;
1808 ;; Besides using multiple bookmark files as *alternatives*, you can
1809 ;; combine them, using them as component bookmark subsets (like
1810 ;; modules). To do that, use command `C-x p l' (lowercase `l'),
1811 ;; which is bound to `bookmark-load', and do not use a prefix
1812 ;; argument. (Using a prefix argument with `C-x p l' is the same as
1813 ;; using `C-x p L': it switches bookmark files.) Here too the
1814 ;; default is the name of the last bookmark file that you used.
1815 ;;
1816 ;; In the `*Bookmark List*' display you can use `M-l' to load all of
1817 ;; the bookmark files corresponding to the marked bookmark-file
1818 ;; bookmarks, in the order in which they are displayed. Any non
1819 ;; bookmark-file bookmarks that are marked are ignored. Before
1820 ;; loading, if any of your currently loaded bookmarks have been
1821 ;; modified then you are asked if you want to save them first, before
1822 ;; loading the others.
1823 ;;
1824 ;; After loading, to avoid confusion and possible mistakes, automatic
1825 ;; saving to the current bookmark file is turned off. You can always
1826 ;; use `M-~' to turn it back on again. And remember that, as long as
1827 ;; you have not saved bookmarks after loading, you can always use
1828 ;; `C-u g' to revert to the bookmarks saved in the bookmark file.
1829 ;;
1830 ;; To create additional bookmark files, to use either as alternatives
1831 ;; or as components, you can either copy an existing bookmark file or
1832 ;; use `bmkp-empty-file' (`C-x p 0') to create a new, empty bookmark
1833 ;; file. If you use `C-x p 0' with an existing bookmark file, then
1834 ;; its bookmarks are all deleted - it is emptied.
1835 ;;
1836 ;; Instead of simply copying a bookmark file, you can use
1837 ;; `bookmark-save' with a prefix argument, or use `bookmark-write'
1838 ;; (bound to `C-x p w'), to save the currently defined bookmarks to a
1839 ;; different bookmark file.
1840 ;;
1841 ;; However a bookmark file was created, you can switch to it and then
1842 ;; add or delete bookmarks selectively, to change its content.
1843 ;; Remember too that you can delete bookmarks from the current set
1844 ;; using command `bookmark-delete' (`C-x p d') or, in the bookmark
1845 ;; list, using `d' plus `x' or marking then `D'.
1846 ;;
1847 ;;
1848 ;;(@* "Bookmark-File Bookmarks")
1849 ;; *** Bookmark-File Bookmarks ***
1850 ;;
1851 ;; A bookmark file is an excellent, persistent way to represent a set
1852 ;; of bookmarks. In particular, it can represent a project or a
1853 ;; project component. Switch among bookmark files to access
1854 ;; different projects. Load project components as you need them.
1855 ;;
1856 ;; You can load a bookmark file using `C-x p L' (switch) or `C-x p l'
1857 ;; (accumulate). As a convenience, you can also load a bookmark file
1858 ;; by jumping to a bookmark-file bookmark.
1859 ;;
1860 ;; You use command `bmkp-set-bookmark-file-bookmark', bound to `C-x p
1861 ;; x', to create a bookmark-file bookmark. Jumping to such a
1862 ;; bookmark just loads the bookmark file that it records. With `C-u'
1863 ;; (e.g. `C-u C-x p j project-foo'), jumping switches bookmark files.
1864 ;; Without `C-u' it accumulates the loaded bookmarks.
1865 ;;
1866 ;; A bookmark-file bookmark is not only an added convenience. You
1867 ;; can also use it in combination with other Bookmark+ features, such
1868 ;; as tagging.
1869 ;;
1870 ;; As a shortcut, in Dired (if you use library Dired+), `C-M-b'
1871 ;; creates a bookmark-file bookmark. The bookmark file that it
1872 ;; records contains autofile bookmarks to each of the files that was
1873 ;; marked in Dired at the time it was created. Jumping to that
1874 ;; bookmark-file bookmark makes those (marked) files available as
1875 ;; bookmarks. See also
1876 ;; (@> "Use Dired to Bookmark Files without Visiting Them").
1877 ;;
1878 ;; Note that the bookmark file in which a bookmark-file bookmark is
1879 ;; recorded is not the same as the bookmark file recorded in that
1880 ;; bookmark.
1881 ;;
1882 ;; For example, when you use `C-M-b' in Dired, the bookmark-file for
1883 ;; the marked files is, by default, file `.emacs.bmk' in the Dired
1884 ;; directory. So if you are in directory `/foo/bar' the default
1885 ;; bookmark file for the marked files is `/foo/bar/.emacs.bmk'. But
1886 ;; the new bookmark-file bookmark created is recorded in the current
1887 ;; bookmark file, whatever that might be (e.g. `~/.emacs.bmk').
1888
1889 ;;(@* "The Bookmark List Display")
1890 ;; ** The Bookmark List Display **
1891 ;;
1892 ;; Bookmark+ enhances the bookmark list (aka the bookmark "menu
1893 ;; list", a misnomer) that is displayed in buffer `*Bookmark List*'
1894 ;; when you use `C-x p e' or `C-x r l' (command
1895 ;; `bookmark-bmenu-list').
1896 ;;
1897 ;; Bookmarks are highlighted to indicate their type. You can mark and
1898 ;; unmark bookmarks, show or hide bookmarks of particular types, and
1899 ;; more. Bookmarks that have tags are marked with a `t'. Bookmarks
1900 ;; that have an annotation are marked with an `a' (not with a `*' as
1901 ;; in vanilla `bookmark.el'). Bookmarks that have been modified
1902 ;; since the last save of the bookmark file are marked with a `*'.
1903 ;; Bookmarks that have bookmark-highlight override settings (see
1904 ;; (@> "Defining How to Highlight")) are marked with a one-character
1905 ;; pink background.
1906 ;;
1907 ;; Use `?' or `C-h m' in buffer `*Bookmark List*' for more
1908 ;; information about the bookmark list, including the following:
1909 ;;
1910 ;; * The current status of sorting, filtering, and marking.
1911 ;;
1912 ;; * A legend for the faces used for different bookmark types.
1913 ;;
1914 ;;
1915 ;;(@* "Tag Commands and Keys")
1916 ;; *** Tag Commands and Keys ***
1917 ;;
1918 ;; There are lots of tag-related bookmark commands, and most are
1919 ;; bound to keys in buffer `*Bookmark List*' as well as to other keys
1920 ;; outside it. How can you keep the commands straight or remember
1921 ;; their keys?
1922 ;;
1923 ;; In the bookmark list display, tags-command keys begin with prefix
1924 ;; key `T'. Elsewhere, they begin with prefix key `C-x p t' (or `C-x
1925 ;; j t', for jump commands - see (@> "Different Types of Jump Commands")).
1926 ;;
1927 ;; `C-h m' (or `?') is your friend, of course. Likewise `T C-h' and
1928 ;; `C-x p t C-h'. Beyond that, the tag-related keys that are more
1929 ;; than two keystrokes are organized as follows:
1930 ;;
1931 ;; They all have the prefix key `T'.
1932 ;;
1933 ;; `m' means mark
1934 ;; `u' means unmark
1935 ;; `>' stands for the marked bookmarks
1936 ;; `*' means AND (set intersection; all)
1937 ;; `+' means OR (set union; some/any)
1938 ;; `~' means NOT (set complement)
1939 ;;
1940 ;; The key `T m *', for instance, marks (`m') the bookmarks that are
1941 ;; tagged with all (`*' = AND) of a given set of tags. It prompts you
1942 ;; for one or more tags that the bookmarks must have, and it marks
1943 ;; all bookmarks that have all of the tags you enter.
1944 ;;
1945 ;; The key `T u ~ +' unmarks (`u') the bookmarks that do not (`~')
1946 ;; have any (`+' = OR) of the tags you specify. And so on.
1947 ;;
1948 ;; The marking and unmarking commands for tags compare the tags a
1949 ;; bookmark has with tags that you enter. Any bookmarks that have no
1950 ;; tags are ignored - they are neither marked nor unmarked by these
1951 ;; commands.
1952 ;;
1953 ;; `+' and `-' can also mean add and remove tags, respectively, and
1954 ;; `>' stands for the marked bookmarks. So `T > +' adds (`+') one or
1955 ;; more tags to each of the marked (`>') bookmarks.
1956 ;;
1957 ;; In general, the tag-related commands let you enter a set of tags,
1958 ;; one at a time. Thus, instead of having a command that adds a
1959 ;; single tag to the current bookmark, you have a command that adds
1960 ;; any number of tags to it. To add just a single tag, hit `RET'
1961 ;; twice: once to enter the tag, and once again to indicate that it
1962 ;; is the last (i.e., the only) one.
1963 ;;
1964 ;; If you just hit `RET' immediately, specifying an empty set of
1965 ;; tags, then each of the commands does something appropriate. For
1966 ;; `T m *', for instance, an empty list of tags means to mark (only)
1967 ;; the bookmarks that have any tags at all.
1968 ;;
1969 ;; Finally, for the marking/unmarking tags commands, a prefix
1970 ;; argument flips the sense of the command, in this way:
1971 ;;
1972 ;; "some are" -> "some are NOT", i.e., "not all are" (and vice versa)
1973 ;; "all are" -> "all are NOT", i.e., "none are" (and vice versa)
1974 ;;
1975 ;; In other words:
1976 ;;
1977 ;; C-u T m * = T m ~ + (all are NOT = not some are)
1978 ;; C-u T m ~ + = T m * (not some are NOT = all are)
1979 ;; C-u T m + = T m ~ * (some are NOT = not all are)
1980 ;; C-u T m ~ * = T m + (not all are NOT = some are)
1981 ;;
1982 ;; You'll figure it out ;-).
1983 ;;
1984 ;; Other important keys pertaining to tags (the keys in parentheses
1985 ;; work in any buffer, not just buffer `*Bookmark List*'):
1986 ;;
1987 ;; * `C-h RET' (`C-x p ?') shows you the tags that belong to a
1988 ;; bookmark. With a prefix argument it shows you the full internal
1989 ;; form of the tags, that is, the name+value pairs.
1990 ;;
1991 ;; * `T e' (`C-x p t e') lets you edit a bookmark's tags.
1992 ;;
1993 ;; * `T l' (`C-x p t l') lists all tags currently known to Emacs
1994 ;; (across all bookmarks).
1995 ;;
1996 ;; * `T +' (`C-x p t + b') adds some tags to a bookmark.
1997 ;; `T -' (`C-x p t - b') removes some tags from a bookmark.
1998 ;; `T 0' (`C-x p t 0) removes all tags from a bookmark.
1999 ;; `T d' (`C-x p t d) removes a set of tags from all bookmarks.
2000 ;;
2001 ;; In the bookmark list display you can also sort bookmarks according
2002 ;; to how they are tagged, even in complex ways. See
2003 ;; (@> "Sorting Bookmarks").
2004 ;;
2005 ;;
2006 ;;(@* "Tags: Sets of Bookmarks")
2007 ;; *** Tags: Sets of Bookmarks ***
2008 ;;
2009 ;; The best way to think about tags is as names of sets. All
2010 ;; bookmarks tagged `blue' constitute the bookmark set named `blue'.
2011 ;;
2012 ;; The bookmarks visible in the bookmark list at any time also
2013 ;; constitute an unnamed set. Likewise, the marked bookmarks and the
2014 ;; unmarked bookmarks are unnamed sets. Bookmark+ is all about
2015 ;; helping you act on sets of Emacs objects. Bookmarks are named,
2016 ;; persistent pointers to objects such as files and file sets.
2017 ;; Bookmark tags are named, persistent sets of bookmarks (and hence
2018 ;; of their target objects).
2019 ;;
2020 ;; The marking commands make it easy to combine sets as unions or
2021 ;; intersections. And you can give the result a name for quick
2022 ;; access later, just by adding a new tag. in other words, do the
2023 ;; set-definition work only once, and name the result.
2024 ;;
2025 ;; How would you tag as `Java IDE Projects' the bookmarks that are
2026 ;; already tagged both `Java' and `ide'?
2027 ;;
2028 ;; 1. `T m * Java RET ide RET RET', to mark them.
2029 ;; 2. `T > + Java IDE Projects RET RET, to tag them.
2030 ;;
2031 ;; How would you sort your bookmarks, to show all those tagged both
2032 ;; `blue' and `moon' first?
2033 ;;
2034 ;; 1. `T m * blue RET moon RET RET', to mark them.
2035 ;; 2. `s >' to sort the marked bookmarks first
2036 ;; (see (@> "Sorting Bookmarks"), below).
2037 ;;
2038 ;; If you wanted to show only the marked bookmarks, instead of
2039 ;; sorting to put them first in the list, you would use `>'
2040 ;; instead of `s >'.
2041 ;;
2042 ;; How would you query-replace the set of files that are tagged with
2043 ;; any of the tags `alpha', `beta', and `gamma', but are not tagged
2044 ;; `blue' or `moon'?
2045 ;;
2046 ;; 1. `F S', to show only the file bookmarks.
2047 ;; 2. `T m + alpha RET beta RET gamma RET RET', to mark the
2048 ;; bookmarks that have at least one of those tags.
2049 ;; 3. `T u + blue RET moon RET RET', to unmark those that are
2050 ;; tagged `blue' or `moon'.
2051 ;; 4. `M-q' to query-replace the marked files.
2052 ;;
2053 ;; If that were a set of files that you used often, then you would
2054 ;; name the set by giving the files a new tag.
2055 ;;
2056 ;; The point is that bookmarks, and bookmark tags in particular, let
2057 ;; you define and manipulate sets of Emacs objects. It doesn't
2058 ;; matter how you define such a set: regexp matching (marking,
2059 ;; filtering), by object type, by tag combinations... Sets need not
2060 ;; be named to act on them, but you can provide them with persistent
2061 ;; names (tags) to avoid redefining them over and over. Manipulation
2062 ;; of bookmarked objects includes visiting, searching, and
2063 ;; query-replacing. And you can define your own bookmark types
2064 ;; (using bookmark handlers) and associated manipulations.
2065 ;;
2066 ;;
2067 ;;(@* "Open Dired for the Marked File Bookmarks")
2068 ;; *** Open Dired for the Marked File Bookmarks ***
2069 ;;
2070 ;; You've seen that the bookmark list has many features that are
2071 ;; similar to Dired features. But Dired is specialized for files and
2072 ;; directories, and it has many more features for manipulating them.
2073 ;; The bookmark list is not intended to replace Dired.
2074 ;;
2075 ;; You can, however, use the bookmark list to take advantage of
2076 ;; arbitrary Dired features for file and directory bookmarks.
2077 ;; Command `bmkp-bmenu-dired-marked' (`M-d >') weds Bookmark+'s
2078 ;; set-defining and set-manipulating features (tagging, marking,
2079 ;; filtering etc.) to Dired's file-manipulating features.
2080 ;;
2081 ;; `M-d >' opens a Dired buffer that is specialized for just the
2082 ;; files and directories whose bookmarks are marked in the bookmark
2083 ;; list. (Other marked bookmarks are ignored by the command.) The
2084 ;; files and directories can be located anywhere; they need not be in
2085 ;; the same directory. They are listed in Dired using absolute file
2086 ;; names.
2087 ;;
2088 ;; (In Emacs versions prior to release 23.2, only local files and
2089 ;; directories can be handled, due to Emacs bug #5478. In such
2090 ;; versions, remote-file bookmarks are ignored by `M-d >'.)
2091 ;;
2092 ;; This Bookmark+ feature makes sets of files and directories
2093 ;; immediately amenable to all of the operations provided by Dired.
2094 ;;
2095 ;; It is particularly useful in conjunction with tags. Use bookmark
2096 ;; tags and marks to define a possibly complex set of file and
2097 ;; directory bookmarks. Then hit `M-d >' to list them in a Dired
2098 ;; buffer. Then use any Dired commands you want to act on any of
2099 ;; them.
2100 ;;
2101 ;; For example, to compress bookmarked files that are tagged with
2102 ;; both `blue' and `moon':
2103 ;;
2104 ;; 1. Mark them using `T m * blue RET moon RET RET'.
2105 ;; 2. Open Dired for them using `M-d >'.
2106 ;; 3. Mark them in Dired, then compress them using `Z'.
2107 ;;
2108 ;; Since tags are persistent, Bookmark+ gives you a good way to
2109 ;; define an arbitrary set of files as a project and then open them
2110 ;; in Dired at any time to operate on them.
2111 ;;
2112 ;; If you use Dired+ (library `dired+.el'), then a similar feature is
2113 ;; available for the marked files and directories: You can use
2114 ;; `C-M-*' in Dired to open a separate Dired buffer for them only.
2115 ;; You can of course then bookmark that resulting Dired buffer, if
2116 ;; you like.
2117 ;;
2118 ;; If you use Icicles, then whenever you use a command that reads a
2119 ;; file (or directory) name, you can use `M-|' during file-name
2120 ;; completion to open Dired on the currently matching set of file
2121 ;; names. That is, this is the same kind of special Dired buffer
2122 ;; that is provided for file and directory bookmarks by `M-d >' in
2123 ;; the bookmark list.
2124 ;;
2125 ;;
2126 ;;(@* "Marking and Unmarking Bookmarks")
2127 ;; *** Marking and Unmarking Bookmarks ***
2128 ;;
2129 ;; Bookmark+ enhances the marking and unmarking of bookmarks in the
2130 ;; bookmark list in several ways. These enhancements are similar to
2131 ;; features offered by Dired and Dired-X. You can use:
2132 ;;
2133 ;; * `% m' to mark the bookmarks that match a regexp. The entire
2134 ;; line in the bookmark list is checked for a match, that is, both
2135 ;; the bookmark name and the file name, if shown.
2136 ;;
2137 ;; * `M-DEL' (or `U') to unmark all bookmarks, or all that are marked
2138 ;; `>', or all that are flagged `D' for deletion.
2139 ;;
2140 ;; * `t' to toggle (swap) the marked and unmarked bookmarks: those
2141 ;; that are marked become unmarked, and vice versa.
2142 ;;
2143 ;; * `>' to show only the marked bookmarks or `<' to show only the
2144 ;; unmarked bookmarks. Repeat to show them all again.
2145 ;;
2146 ;; * `F M', `I M' etc. to mark only the file bookmarks, Info
2147 ;; bookmarks etc. (The first key here is the same as the
2148 ;; corresponding filter key, e.g. `F' for files - see next topic.)
2149 ;;
2150 ;; * `O M' to mark the orphaned bookmarks, that is, those whose
2151 ;; recorded files have been renamed or deleted. You can then
2152 ;; relocate or delete the bookmarks, as appropriate.
2153 ;;
2154 ;;
2155 ;;(@* "Filtering Bookmarks (Hiding and Showing)")
2156 ;; *** Filtering Bookmarks (Hiding and Showing) ***
2157 ;;
2158 ;; You can hide and show different sets of bookmarks in the bookmark
2159 ;; list. There are commands to show only bookmarks of a particular
2160 ;; type - e.g. `I S' to show only Info bookmarks, `X S' to show only
2161 ;; the temporary bookmarks.
2162 ;;
2163 ;; These are, in effect, shortcuts for first marking those bookmarks
2164 ;; and then showing only the marked bookmarks (and then unmarking).
2165 ;; For example, `F S' is a shortcut for `F M >' (and then `U RET').
2166 ;;
2167 ;; You can also filter to show only the bookmarks that match a given
2168 ;; regexp. There are two ways to do this:
2169 ;;
2170 ;; * Use `P B' (for "pattern", "bookmark") and type a regexp. The
2171 ;; bookmarks are filtered incrementally, as you type. Only the
2172 ;; bookmark name is matched (not the file name). Hit any
2173 ;; non-inserting key, such as `RET', to finish defining the
2174 ;; pattern.
2175 ;;
2176 ;; Similarly, hit `P F' for bookmarks whose file names match a
2177 ;; regexp, `P A' for bookmarks whose annotations match a regexp,
2178 ;; and `P T' for bookmarks with one or more tags that match a
2179 ;; regexp. See (@> "Bookmark Tags"), above, for information about
2180 ;; tags.
2181 ;;
2182 ;; * Just as in Dired, use `% m' to mark the bookmarks that match a
2183 ;; regexp. Then use `>' to show only the marked bookmarks. See
2184 ;; (@> "Marking and Unmarking Bookmarks"), above.
2185 ;;
2186 ;; This method has the advantage that you can show the complement,
2187 ;; the bookmarks that do *not* match the regexp, by using `<'
2188 ;; instead of `>'. It also has the advantage that matching checks
2189 ;; the combination of bookmark name and file name (use `M-t' to
2190 ;; toggle showing file names).
2191 ;;
2192 ;;
2193 ;;(@* "Only Visible Bookmarks Are Affected")
2194 ;; *** Only Visible Bookmarks Are Affected ***
2195 ;;
2196 ;; Commands that operate on the current bookmark or on the marked or
2197 ;; the unmarked bookmarks act only on bookmarks that are displayed
2198 ;; (not hidden). This includes the commands that mark or unmark
2199 ;; bookmarks. This means that you can easily define any given set of
2200 ;; bookmarks.
2201 ;;
2202 ;; For example:
2203 ;;
2204 ;; Use `F S' to show only bookmarks associated with files.
2205 ;; Use `% m' to mark those that match a particular regexp.
2206 ;; Use `R S' to show only bookmarks that have regions.
2207 ;; Use `m' to mark some of those region bookmarks individually.
2208 ;; Use `.' to show all bookmarks.
2209 ;; Use `t' to swap marked and unmarked (so unmarked are now marked)
2210 ;; Use `D' to delete all of the marked bookmarks (after confirming)
2211 ;;
2212 ;; Together, steps 1-7 delete all file bookmarks that match the
2213 ;; regexp and all region bookmarks that you selectively marked.
2214 ;;
2215 ;;
2216 ;;(@* "Omitting Bookmarks from Display")
2217 ;; *** Omitting Bookmarks from Display ***
2218 ;;
2219 ;; In sections (@> "Marking and Unmarking Bookmarks") and
2220 ;; (@> "Filtering Bookmarks (Hiding and Showing)") you learned how
2221 ;; to hide and show bookmarks in the bookmark list. This section is
2222 ;; about a different kind of hiding, called "omitting".
2223 ;;
2224 ;; Omitted bookmarks are not shown in the bookmark list, no matter
2225 ;; what filtering is used. The only way to show omitted bookmarks is
2226 ;; to show all of them and only them, using `- S', which is bound to
2227 ;; command `bmkp-bmenu-show-only-omitted'.
2228 ;;
2229 ;; Omitted bookmarks are still available even if they are not shown,
2230 ;; and you can still jump to them (e.g. using `C-x r b'). You just
2231 ;; don't see them in the bookmark list. And that's the reason for
2232 ;; this feature: to hide those bookmarks that you don't care to see.
2233 ;;
2234 ;; One use for this feature is to hide the component bookmarks that
2235 ;; make up a sequence bookmark (see
2236 ;; (@> "Function, Sequence, and Variable-List Bookmarks")). The
2237 ;; default behavior when you create a sequence bookmark is in fact to
2238 ;; omit its component bookmarks from the displayed list.
2239 ;;
2240 ;; You can omit any bookmarks by marking them and then using `- >'
2241 ;; (`bmkp-bmenu-omit/unomit-marked'). If you are looking at the
2242 ;; omitted bookmarks (after using `- S'), then `- >' un-omits the
2243 ;; bookmarks marked there. Think of two complementary spaces: the
2244 ;; normal bookmark list and the omitted bookmark list. When you use
2245 ;; `- >', the marked bookmarks that are currently shown are moved to
2246 ;; the opposite space.
2247 ;;
2248 ;; You can un-omit all of the omitted bookmarks at once, using `- U'
2249 ;; (`bmkp-unomit-all'). You can also call this command from outside
2250 ;; the bookmark-list display.
2251 ;;
2252 ;;
2253 ;;(@* "Sorting Bookmarks")
2254 ;; *** Sorting Bookmarks ***
2255 ;;
2256 ;; Filtering hides certain kinds of bookmarks. Sometimes, you want
2257 ;; to see bookmarks of various kinds, but you want them to be grouped
2258 ;; or sorted in different ways, for easy recognition, comparison, and
2259 ;; access.
2260 ;;
2261 ;; Bookmarks shown in the bookmark list are sorted using the current
2262 ;; value of option `bmkp-sort-comparer'. (If that is nil, they are
2263 ;; unsorted, which means they appear in reverse chronological order
2264 ;; of their creation.)
2265 ;;
2266 ;; You can use `s s'... (repeat hitting the `s' key) to cycle among
2267 ;; the various sort orders possible, updating the display
2268 ;; accordingly. By default, you cycle among all available sort
2269 ;; orders, but you can shorten the cycling list by customizing option
2270 ;; `bmkp-sort-orders-for-cycling-alist'.
2271 ;;
2272 ;; You can also change directly to one of the main sort orders
2273 ;; (without cycling) using `s >', `s n', `s f n', etc. There are
2274 ;; many such predefined sort orders bound to keys with the prefix `s'
2275 ;; - use `C-h m' or `?' for more info.
2276 ;;
2277 ;; You can reverse the current sort direction (ascending/descending)
2278 ;; using `s r'. Also, repeating any of the main sort-order commands
2279 ;; (e.g. `s n') cycles among that order, the reverse, and unsorted.
2280 ;;
2281 ;; For a complex sort, which involves composing several sorting
2282 ;; conditions, you can also use `s C-r' to reverse the order of
2283 ;; bookmark sorting groups or the order within each group (depending
2284 ;; on whether `s r' is also used). Be aware that this can be a bit
2285 ;; unintuitive. If it does not do what you expect or want, or if it
2286 ;; confuses you, then don't use it ;-). (`s C-r' has no noticeable
2287 ;; effect on simple sorting.)
2288 ;;
2289 ;; Remember that you can combine sorting with filtering different
2290 ;; sets of bookmarks - bookmarks of different kinds (e.g. Info) or
2291 ;; bookmarks that are marked or unmarked.
2292 ;;
2293 ;; Finally, you can easily define your own sorting commands and sort
2294 ;; orders. See macro `bmkp-define-sort-command' and the
2295 ;; documentation for option `bmkp-sort-comparer'. (Bookmark+ uses
2296 ;; option `bmkp-sort-comparer'; it *ignores* vanilla Emacs option
2297 ;; `bookmark-sort-flag'.)
2298 ;;
2299 ;; Of particular note is that you can interactively define commands
2300 ;; that sort by a given list of tags - you use keys `T s' (command
2301 ;; `bmkp-define-tags-sort-command') to do that. You are prompted for
2302 ;; the tags to sort by. Bookmarks are sorted first according to
2303 ;; whether they are tagged with the first tag, then the second tag,
2304 ;; and so on. Otherwise, sorting is by bookmark name.
2305 ;;
2306 ;; The tags you specify are used, in order, in the name of the new
2307 ;; command. For example, if you enter tags `alpha', `beta', and
2308 ;; `gamma', in that order, then the sorting command created is
2309 ;; `bmkp-bmenu-sort-alpha-beta-gamma'. The new command is saved in
2310 ;; your bookmark commands file (`bmkp-bmenu-commands-file').
2311 ;;
2312 ;; Note that because you can add a new tag to all bookmarks that have
2313 ;; some given set of tags, you can use that single (new) tag to
2314 ;; represent the entire tag set. Sorting by that tag is then the
2315 ;; same as sorting by the tag set. You can of course use overlapping
2316 ;; sets in the composite sort command. You can, for example, sort
2317 ;; first according to tag `tag1', which represents the set of tags
2318 ;; `alpha', `beta', `gamma', `delta', and then sort according to tag
2319 ;; `tag2', which represents the set of tags `beta', `delta'.
2320 ;;
2321 ;; See also (@> "Use Bookmark+ with Icicles") - the same technique is
2322 ;; used in Icicles for sorting bookmarks as completion candidates.
2323
2324 ;;(@* "Bookmarks for Specific Files or Buffers")
2325 ;; ** Bookmarks for Specific Files or Buffers **
2326 ;;
2327 ;; A bookmark typically records a position or a region in a file or
2328 ;; buffer. Sometimes you are interested in accessing or examining
2329 ;; only the bookmarks for particular files or buffers. For example,
2330 ;; you might want to navigate among the bookmarks for the current
2331 ;; buffer. Or you might want to search the regions recorded in the
2332 ;; bookmarks for a particular file.
2333 ;;
2334 ;; For a bookmark, the recorded file and buffer name differ in that
2335 ;; the file name is absolute. Bookmarks for buffer `foo.el' include
2336 ;; all files named `foo.el', whereas bookmarks for file
2337 ;; `/project1/lisp/foo.el' include only the files in that one
2338 ;; directory.
2339 ;;
2340 ;; Another important difference is that when multiple buffers visit
2341 ;; different files that have the same relative file name (i.e., in
2342 ;; different directories), Emacs makes the buffer names unique by
2343 ;; appending `<N>' as needed, where `N' is 2, 3,... When you create
2344 ;; a bookmark, the current buffer name is recorded as the bookmark's
2345 ;; buffer. If the current buffer is not visiting a file, then the
2346 ;; bookmark created is a non-file bookmark. In that case, to use the
2347 ;; bookmark later you must have a buffer of the same name
2348 ;; (e.g. `foo.el<2>').
2349 ;;
2350 ;; Bookmark+ provides commands to handle these different use cases:
2351 ;; specific files and specific buffers. The keys bound to these
2352 ;; commands use `f' for file and `b' for buffer. In the
2353 ;; bookmark-list display, the following keys affect the bookmarks for
2354 ;; a particular file or buffer whose name you provide (with
2355 ;; completion).
2356 ;;
2357 ;; * `= f M' and `= b M' - mark
2358 ;; * `= f S' and `= b S' - show (only)
2359 ;;
2360 ;; For navigation, the following keys jump to bookmarks for
2361 ;; particular files or buffers. (Use `C-x 4 j' for other-window.)
2362 ;;
2363 ;; * `C-x j ,,' - current buffer
2364 ;; * `C-x j = f' and `C-x j = b' - specified file(s) or buffer(s)
2365 ;;
2366 ;; For the `=' keys you are prompted for one or more file names or
2367 ;; buffer names.
2368 ;;
2369 ;; Finally, because the bookmarks in the current buffer can be of
2370 ;; particular interest, `C-x p ,' opens the bookmark-list display for
2371 ;; only those bookmarks. (`,' stands generally for "this-buffer" in
2372 ;; Bookmark+ key bindings.)
2373
2374 ;;(@* "Cycling, Navigation List")
2375 ;; ** "Cycling, Navigation List" **
2376 ;;
2377 ;; Using completion to jump to a bookmark is handy. It lets you
2378 ;; choose a bookmark by its name and gives you direct ("random")
2379 ;; access to it.
2380 ;;
2381 ;; Sometimes, however, you don't much care what a bookmark is named,
2382 ;; and you want to cycle quickly among relatively few, related
2383 ;; bookmarks. Obviously, the smaller the number of bookmarks in the
2384 ;; set, the more convenient cycling is - with many bookmarks cycling
2385 ;; can become tedious.
2386 ;;
2387 ;; An analogy: If your TV has lots of channels, then the channel
2388 ;; up/down buttons on the remote control are not so useful: 32, 33,
2389 ;; 34, ..., 79! Unless the channel you want happens to be near the
2390 ;; current channel, cycling around a huge ring of channels is not the
2391 ;; way to go. And just because your TV receives lots of channels
2392 ;; does not mean that you watch them all or that you are equally
2393 ;; interested in them all.
2394 ;;
2395 ;; Some TV remote controls have a feature that mitigates this
2396 ;; problem. You can define a ring of favorite channels, and there
2397 ;; are two additional buttons that let you cycle forward and backward
2398 ;; around the ring, skipping the channels in between. The number of
2399 ;; favorites is relatively small, so cycling is not tedious. More
2400 ;; importantly, all of the channels in the ring are ones you are
2401 ;; interested in.
2402 ;;
2403 ;; Extend this idea to allow for assigning different sets of channels
2404 ;; to the favorites ring at different times: choose the ring you want
2405 ;; at any time: sports, music, films, science, art, history, and so
2406 ;; on. Add the possibility of sorting those sets in various ways, to
2407 ;; further facilitate cycling, and you arrive at the idea behind the
2408 ;; Bookmark+ navigation list.
2409 ;;
2410 ;; Another analogy is a music playlist. You can use Bookmark+ as a
2411 ;; simple music player by bookmarking music files. Similarly, you
2412 ;; can use Bookmark+ to create slideshows by bookmarking image files.
2413 ;; Cycle the navigation list to move through the slide show.
2414 ;;
2415 ;; If you use MS Windows, you can take advantage of your existing
2416 ;; file associations to open your bookmarks using the appropriate
2417 ;; program - no need to define a new bookmark type and handler. See
2418 ;; (@> "Bookmarking Files That You Cannot Visit with Emacs").
2419 ;;
2420 ;; Note: The default value of option `bmkp-use-region' is `t', not
2421 ;; `cycling-too', which means that when you cycle to a bookmark its
2422 ;; recorded region (if any) is not activated. This is probably what
2423 ;; you want most of the time. Cycling is a repetitive action, and if
2424 ;; you cycle to a bookmark with no recorded region then an already
2425 ;; active region is just extended. Customize the value to
2426 ;; `cycling-too' if you prefer that behavior.
2427 ;;
2428 ;;
2429 ;;(@* "The Bookmark Navigation List")
2430 ;; *** "The Bookmark Navigation List ***
2431 ;;
2432 ;; Bookmark+ is all about letting you define and manipulate sets of
2433 ;; bookmarks. When a bookmark set can be used for cycling (as well
2434 ;; as jumping) it is called the "navigation list" or "navlist", for
2435 ;; short.
2436 ;;
2437 ;; In other words, Bookmark+ lets you cycle among any set of
2438 ;; bookmarks. When you cycle, it is the set that currently
2439 ;; constitutes the navigation list that is cycled.
2440 ;;
2441 ;; Here are two ways to define the navigation list:
2442 ;;
2443 ;; * `C-x p :' (`bmkp-choose-navlist-of-type') - As the set of all
2444 ;; bookmarks of a certain type (`any' or empty input means use all
2445 ;; bookmarks).
2446 ;;
2447 ;; * `C-x p B' (`bmkp-choose-navlist-from-bookmark-list') - As the
2448 ;; set of all bookmarks corresponding to a bookmark-list bookmark,
2449 ;; that is the bookmarks corresponding to a given recorded state of
2450 ;; buffer `*Bookmark List*'.
2451 ;;
2452 ;; Each of these lets you choose a set of bookmarks using completion.
2453 ;; For `C-x p :' you are prompted for the type of bookmark
2454 ;; (e.g. `dired').
2455 ;;
2456 ;; For `C-x p B' you are prompted for the name of a bookmark-list
2457 ;; bookmark that you created. But you can also choose the candidate
2458 ;; `CURRENT *Bookmark List*' to capture the bookmarks that would be
2459 ;; shown currently in the `*Bookmark List*' (even if the list is not
2460 ;; displayed now). See (@> "State-Restoring Commands and Bookmarks")
2461 ;; for information about bookmark-list bookmarks.
2462 ;;
2463 ;; If you do not define the navigation list before you start cycling,
2464 ;; it is automatically defined as follows:
2465 ;;
2466 ;; * If you cycle using a current-file/buffer cycling key such as
2467 ;; `C-x p down' (see (@> "Cycling in the Current File/Buffer"))
2468 ;; then the bookmarks in the current file or buffer are used as the
2469 ;; navlist.
2470 ;;
2471 ;; * Otherwise, a snapshot is taken of the the bookmarks currently in
2472 ;; the global bookmark list (the value of variable
2473 ;; `bookmark-alist') as the navlist.
2474 ;;
2475 ;; However the navlist is defined, it is important to remember this:
2476 ;; it is a static snapshot of some set of bookmarks taken at a given
2477 ;; time. Subsequent changes to the bookmark list that was copied are
2478 ;; not reflected in the navlist. If you add a bookmark it will not
2479 ;; be among those cycled. But see also
2480 ;; (@> "Cycling Dynamic Sets of Bookmarks") for how to cycle dynamic
2481 ;; sets.
2482 ;;
2483 ;; You can update the navlist at any time by taking another snapshot
2484 ;; of the same bookmark list you used for the last snapshot. For the
2485 ;; global bookmark list just use `C-x p : RET'. (You can of course
2486 ;; bind that action to a shorter key sequence if you like.)
2487 ;;
2488 ;; Besides cycling among the bookmarks of the navlist (see next),
2489 ;; once you have defined the navigation list you can use `C-x j N' or
2490 ;; `C-x 4 j N' to jump to its bookmarks, as mentioned in section
2491 ;; (@> "Different Types of Jump Commands").
2492 ;;
2493 ;; Note that just because you might have used `C-x p B' to define the
2494 ;; navlist using a particular bookmark-list bookmark or the current
2495 ;; `*Bookmark List*' state, that does not mean that the `*Bookmark
2496 ;; List*' state at any given time necessarily reflects the navlist
2497 ;; bookmarks. The two are separate. You can, however, open the
2498 ;; `*Bookmark List*' so that it reflects the bookmarks currently in
2499 ;; the navigation list, using `C-x p N' (`bmkp-navlist-bmenu-list').
2500 ;;
2501 ;;
2502 ;;(@* "Cycling the Navigation List")
2503 ;; *** "Cycling the Navigation List" ***
2504 ;;
2505 ;; So you choose a navigation list. How do you then cycle among its
2506 ;; bookmarks?
2507 ;;
2508 ;; Commands `bmkp-next-bookmark' and `bmkp-previous-bookmark' cycle
2509 ;; to the next and previous bookmark in the navigation list (with
2510 ;; wraparound).
2511 ;;
2512 ;; You can bind these to any keys you like, but it's obviously better
2513 ;; to choose keys that are easily repeatable (e.g. by holding them
2514 ;; pressed). Some people who are used to using MS Visual Studio
2515 ;; might want to use `f2' and `S-f2' to cycle forward and backward.
2516 ;;
2517 ;; Bookmark+ does not define such key bindings, but you can. What it
2518 ;; does is define repeatable keys on the `bookmark-map' keymap, which
2519 ;; has prefix `C-x p'. To do this it binds similar commands that can
2520 ;; be repeated by simply repeating the key-sequence suffix. These
2521 ;; are the keys:
2522 ;;
2523 ;; Forward: `C-x p f', `C-x p C-f', `C-x p right'
2524 ;; Backward: `C-x p b', `C-x p C-b', `C-x p left'
2525 ;;
2526 ;; (If you use an Emacs version prior to Emacs 22, you cannot use
2527 ;; this prefix-key repeatable feature.)
2528 ;;
2529 ;; In addition, if you use MS Windows then you can invoke the Windows
2530 ;; `Open' action on each bookmark when you cycle, to act on its file
2531 ;; using the program associated with the file type. This lets you
2532 ;; play music or display images in a playlist or slideshow fashion.
2533 ;; These are the keys to do that:
2534 ;;
2535 ;; Forward: `C-x p next' (PageDown key)
2536 ;; Backward: `C-x p prior' (PageUp key)
2537 ;;
2538 ;; Being able to cycle among an arbitrary set of bookmarks is the
2539 ;; most important feature of Bookmark+ cycling. The other important
2540 ;; feature is that if the navigation list is defined by `*Bookmark
2541 ;; List*' then the characteristics of that bookmark display are
2542 ;; respected for navigation. Only the bookmarks visible in
2543 ;; `*Bookmark List*' are included, and the `*Bookmark List*' sort
2544 ;; order is used for navigation.
2545 ;;
2546 ;; So you can not only choose any set of bookmarks for cycling at any
2547 ;; given time, you can also cycle among them in an order you choose.
2548 ;; For example, if in the bookmark list display (`C-x p e' or `C-x r
2549 ;; l') you show only those file bookmarks that belong to a given
2550 ;; project, and you have them sorted by file size, then cycling moves
2551 ;; among only those files, in file-size order.
2552 ;;
2553 ;; This is a main reason you will want to define bookmark-list
2554 ;; bookmarks, which record a specific set of bookmarks and their sort
2555 ;; order: to later choose given sets in different contexts for
2556 ;; cycling.
2557 ;;
2558 ;;
2559 ;;(@* "Cycling Dynamic Sets of Bookmarks")
2560 ;; *** "Cycling Dynamic Sets of Bookmarks" ***
2561 ;;
2562 ;; The fact that the navlist is a static snapshot is a useful
2563 ;; feature, but sometimes you might want to cycle among a particular
2564 ;; dynamic set of bookmarks, that is, to have cycling take changes to
2565 ;; the bookmark set into account automatically. For that, Bookmark+
2566 ;; provides separate cycling commands for most types of bookmark.
2567 ;;
2568 ;; By default, these different kinds of cycling commands are not
2569 ;; bound to any keys, with the exception of the commands for cycling
2570 ;; the current fle or buffer. This exception includes cycling all
2571 ;; bookmarks for the current file/buffer
2572 ;; (see (@> "Cycling in the Current File/Buffer")
2573 ;; and cycling only the highlighted bookmarks for the current
2574 ;; file/buffer (see (@> "Using Highlighted Bookmarks")). Keys `C-x p
2575 ;; down' and `C-x p C-down' are defined for these two kinds of
2576 ;; current-buffer cycling.
2577 ;;
2578 ;; If you often want to cycle among the bookmarks of some other
2579 ;; particular kind (e.g. only the autonamed bookmarks), then you can
2580 ;; bind the relevant commands
2581 ;; (e.g. `bmkp-next-autonamed-bookmark-repeat',
2582 ;; `bmkp-previous-autonamed-bookmark-repeat') to handy keys.
2583 ;; Otherwise, you can just use the cycling commands without binding
2584 ;; them.
2585 ;;
2586 ;;
2587 ;;(@* "Cycling in the Current File/Buffer")
2588 ;; *** "Cycling in the Current File/Buffer" ***
2589 ;;
2590 ;; You can navigate the bookmarks in the current file or buffer by
2591 ;; cycling as well as jumping. It is convenient to have dedicated
2592 ;; keys for this, separate from the keys to cycle the navigation
2593 ;; list. The following keys are defined, corresponding to commands
2594 ;; `bmkp-next-bookmark-this-file/buffer-repeat' and
2595 ;; `bmkp-previous-bookmark-this-file/buffer-repeat':
2596 ;;
2597 ;; Next: `C-x p n', `C-x p C-n', `C-x p down'
2598 ;; Previous: `C-x p p', `C-x p C-p', `C-x p up'
2599 ;;
2600 ;; Starting with Emacs 23.3 (Emacs fix for bug #6256), you can also
2601 ;; use the mouse wheel to cycle: `C-x p' then just rotate the wheel.
2602 ;;
2603 ;; Again, you can bind any keys you want to these commands
2604 ;; (e.g. `f2', `S-f2'). If you do not need to use a prefix key, then
2605 ;; bind commands `bmkp-next-bookmark-this-file/buffer' and
2606 ;; `bmkp-previous-bookmark-this-file/buffer' (no -repeat).
2607 ;;
2608 ;; You can also cycle among just the highlighted bookmarks in the
2609 ;; current file or buffer - see (@> "Using Highlighted Bookmarks").
2610 ;;
2611 ;; Cycling among bookmarks for the current file or buffer (whether
2612 ;; all or only the highlighted ones) is dynamic: the current set of
2613 ;; bookmarks is cycled, not a static snapshot taken at some point in
2614 ;; past. The navlist is automatically updated to the current dynamic
2615 ;; set each time you cycle. This is different from the usual cycling
2616 ;; of the navlist, where it is taken as a static snapshot -
2617 ;; see (@> "The Bookmark Navigation List").
2618 ;;
2619 ;; By default, you cycle among the bookmarks for the current file or
2620 ;; buffer in order of their buffer positions, top to bottom. If you
2621 ;; want a different order, you can customize option
2622 ;; `bmkp-this-file/buffer-cycle-sort-comparer'.
2623 ;;
2624 ;; Alternatively, you can use `C-x p ,' to display the `*Bookmark
2625 ;; List*' with only the current file/buffer's bookmarks, sort them
2626 ;; there, and then use `C-x p B' to set the navigation list to
2627 ;; `CURRENT *Bookmark List*'. In that case, you use the navlist
2628 ;; cycling keys (e.g. `C-x p f', not `C-x p n'), and the cycled set
2629 ;; is a static snapshot.
2630 ;;
2631 ;; Note that the keys mentioned here cycle bookmarks for the current
2632 ;; file if visiting a file, or the current buffer otherwise. There
2633 ;; are also commands (unbound to keys) for cycling bookmarks for the
2634 ;; current file only or the current buffer only.
2635 ;;
2636 ;; The bookmarks for the current buffer are those that were created
2637 ;; in a buffer of exactly the same name. If one buffer visits a file
2638 ;; `foo.el', and another buffer visits a different file of the same
2639 ;; name (i.e., in a different directory), the second buffer will have
2640 ;; the name `foo.el<2>'. The buffer name is recorded when you create
2641 ;; a bookmark. If you later use same-buffer cycling then the
2642 ;; bookmarks cycled are only those created with the same buffer name
2643 ;; as the current buffer.
2644 ;;
2645 ;; This is the reason why the `*-file/buffer*' commands are bound to
2646 ;; keys. They are usually what you want. They try first to work
2647 ;; with bookmarks for the same file as the current buffer, if it is
2648 ;; visiting a file.
2649
2650 ;;(@* "Autonamed Bookmarks - Easy Come Easy Go")
2651 ;; ** "Autonamed Bookmarks - Easy Come Easy Go" **
2652 ;;
2653 ;; Sometimes it is convenient to quickly create and delete bookmarks
2654 ;; whose names you don't really care about. That is the purpose of
2655 ;; "autonamed" bookmarks. An autonamed bookmark has a simple name
2656 ;; provided automatically, and it does not record any region
2657 ;; information - it records only a position. An autonamed bookmark
2658 ;; is nevertheless an ordinary, persistent bookmark.
2659 ;;
2660 ;; `C-x p RET' creates a bookmark at point without prompting you for
2661 ;; the name. It is named using the current buffer name preceded by
2662 ;; the position in the buffer. For example, the autonamed bookmark
2663 ;; in buffer `foo.el' at position 58356 is `000058356 foo.el'.
2664 ;;
2665 ;; (You can customize the format of autonamed bookmarks using options
2666 ;; `bmkp-autoname-bookmark-function' and `bmkp-autoname-format'.)
2667 ;;
2668 ;; When you jump to any bookmark, the actual destination can differ
2669 ;; from the recorded position, because the buffer text might have
2670 ;; changed. In that case, the position you jump to has been
2671 ;; automatically relocated using the recorded bookmark context (some
2672 ;; buffer text surrounding the original position).
2673 ;;
2674 ;; If option `bmkp-save-new-location-flag' is non-nil then, after
2675 ;; jumping, the recorded position of the bookmark is automatically
2676 ;; updated to reflect the new location jumped to. This is true for
2677 ;; any bookmark.
2678 ;;
2679 ;; In the case of an autonamed bookmark, the bookmark name reflects
2680 ;; the recorded position when you create it. And when you jump to
2681 ;; it, both the name and the recorded position are updated to reflect
2682 ;; the jump destination. So jumping to an autonamed bookmark keeps
2683 ;; its persistent record in sync with the buffer location.
2684 ;;
2685 ;; You will thus notice that the names of autonamed bookmarks can
2686 ;; change as you visit them (e.g. cycling). The bookmarks are
2687 ;; automatically repositioned following their recorded contexts, and
2688 ;; their names reflect that repositioning.
2689 ;;
2690 ;; It is only when you jump to a bookmark that it is repositioned
2691 ;; this way, and only if needed. It is normal that some bookmarks
2692 ;; become somewhat out of sync with their original positions as you
2693 ;; edit the text in the buffer. In addition, if you highlight
2694 ;; bookmarks then you will notice the highlighting move as you edit
2695 ;; nearby text. The recorded bookmark has not changed, but its
2696 ;; highlight has moved. The highlight moves more or less as if it
2697 ;; were an Emacs marker. When you jump to the bookmark and it is thus
2698 ;; updated, the highlight moves back to the recorded position,
2699 ;; adjusted perhaps to fit the recorded context.
2700 ;;
2701 ;; `C-x p RET' is `bmkp-toggle-autonamed-bookmark-set/delete', and it
2702 ;; does double duty. If an autonamed bookmark is under the cursor,
2703 ;; then `C-x p RET' deletes it. Easy creation, easy deletion.
2704 ;; Because of this toggle behavior, there is at most one autonamed
2705 ;; bookmark at any given buffer position.
2706 ;;
2707 ;; `C-x p RET' has a third use: With a prefix argument, it prompts
2708 ;; you to confirm the deletion of *all* autonamed bookmarks for the
2709 ;; current buffer.
2710 ;;
2711 ;; (You can also use `C-x p delete' (that's the `delete' key), bound
2712 ;; to `bmkp-delete-bookmarks', to delete individual bookmarks under
2713 ;; the cursor or all bookmarks in the buffer. This is not limited to
2714 ;; autonamed bookmarks.)
2715 ;;
2716 ;; In addition to `C-x p RET', you can create autonamed bookmarks
2717 ;; using these commands:
2718 ;;
2719 ;; * `bmkp-set-autonamed-bookmark-at-line' - At a line beginning
2720 ;; * `bmkp-set-autonamed-regexp-buffer' - At buffer matches
2721 ;; * `bmkp-set-autonamed-regexp-region' - At region matches
2722 ;; * `bmkp-occur-create-autonamed-bookmarks' (`C-c b' in `*Occur*') -
2723 ;; At `occur' and `multi-occur' hits
2724 ;;
2725 ;; Autonamed bookmarks are normal bookmarks. In particular, they are
2726 ;; persisted. If you do not care to persist them, you can ensure
2727 ;; that they are automatically deleted by adding
2728 ;; `bmkp-delete-autonamed-this-buffer-no-confirm' to
2729 ;; `kill-buffer-hook' and `bmkp-delete-autonamed-no-confirm' to
2730 ;; `kill-emacs-hook':
2731 ;;
2732 ;; (add-hook 'kill-buffer-hook
2733 ;; 'bmkp-delete-autonamed-this-buffer-no-confirm)
2734 ;; (add-hook 'kill-emacs-hook
2735 ;; 'bmkp-delete-autonamed-no-confirm)
2736
2737 ;;(@* "Temporary Bookmarks")
2738 ;; ** Temporary Bookmarks **
2739 ;;
2740 ;; Autonamed bookmarks are easy-come-easy-go in the sense that `C-x p
2741 ;; RET' either sets (creates) one or deletes the one under the
2742 ;; cursor. But what about temporary bookmarks in general? What if
2743 ;; you want only bookmarks that are temporary, that is, not saved to
2744 ;; disk? Or what if you want certain kinds of bookmarks to always be
2745 ;; temporary? Or what if you want to toggle whether particular
2746 ;; bookmarks get saved automatically?
2747 ;;
2748 ;;(@* "Temporary Bookmarking Mode")
2749 ;; *** Temporary Bookmarking Mode ***
2750 ;;
2751 ;; As always, you can control whether the bookmarks in the current
2752 ;; bookmark list are saved automatically using option
2753 ;; `bookmark-save-flag'. Remember that you can toggle this option
2754 ;; using command `bmkp-toggle-saving-bookmark-file' (bound to `M-~'
2755 ;; in the bookmark-list buffer). Remember too that you can at any
2756 ;; time change the set of available bookmarks (the bookmark list),
2757 ;; which means also changing the set of bookmarks that are
2758 ;; susceptible to being saved.
2759 ;;
2760 ;; You could, for example:
2761 ;;
2762 ;; 1. Use `C-x p 0' (`bmkp-empty-file') to create a new, empty
2763 ;; bookmark file.
2764 ;;
2765 ;; 2. Use `C-x p L' (`bmkp-switch-bookmark-file-create') to switch to
2766 ;; using that new, empty bookmark file.
2767 ;;
2768 ;; 3. Use `M-x bmkp-toggle-saving-bookmark-file' to turn off
2769 ;; auto-saving bookmarks to disk.
2770 ;;
2771 ;; This is essentially what the minor-mode toggle command
2772 ;; `bmkp-temporary-bookmarking-mode' does. When in this minor mode,
2773 ;; bookmarks that you create are stored on the new bookmark list,
2774 ;; which is not automatically saved to disk. If you do not
2775 ;; explicitly save it yourself then the bookmarks are lost when your
2776 ;; Emacs session ends - they are only temporary.
2777 ;;
2778 ;; This command is bound to `M-L' in the bookmark-list display buffer
2779 ;; (`*Bookmark List*'). The suffix `L' indicates that this has to do
2780 ;; with loading a bookmark file. See (@> "Using Multiple Bookmark Files").
2781 ;;
2782 ;; In the bookmark-list display, temporary bookmarking mode is
2783 ;; indicated in the mode line by `TEMPORARY Bookmarking' in place of
2784 ;; `Bookmarks' as the mode name.
2785 ;;
2786 ;;(@* "Making Bookmarks Temporary")
2787 ;; *** Making Bookmarks Temporary ***
2788 ;;
2789 ;; Instead of simply switching to a temporary bookmark list, so that
2790 ;; *all* bookmarking is only temporary, you more often want to have
2791 ;; some bookmarks be temporary while still ensuring that others get
2792 ;; saved. Or you temporarily want all new bookmarks that you create
2793 ;; and all bookmarks that you update to be temporary, without
2794 ;; affecting other, unchanged bookmarks.
2795 ;;
2796 ;; You can control this at the level of individual bookmarks, types
2797 ;; of bookmarks, or all bookmarks whenever they are set (created or
2798 ;; updated).
2799 ;;
2800 ;; * At the individual-bookmark level, commands
2801 ;; `bmkp-make-bookmark-temporary' and `bmkp-make-bookmark-savable'
2802 ;; prompt you for a bookmark name and then set its
2803 ;; temporary/savable status. Command
2804 ;; `bmkp-toggle-temporary-bookmark' combines these commands,
2805 ;; toggling the status for a given bookmark.
2806 ;;
2807 ;; In the bookmark list, this toggle is bound to `C-M-X'. There
2808 ;; are also commands in the bookmark-list display to toggle the
2809 ;; temporary/savable status of the marked bookmarks (`M-X'), to
2810 ;; mark the temporary bookmarks (`X M'), and to show only the
2811 ;; temporary bookmarks (`X S').
2812 ;;
2813 ;; * At the bookmark-type level, you can customize user option
2814 ;; `bmkp-autotemp-bookmark-predicates'. It is a list of bookmark
2815 ;; predicates - typically type predicates - that define which
2816 ;; bookmarks are automatically made temporary whenever they are
2817 ;; set.
2818 ;;
2819 ;; The default value includes the type predicates for autonamed
2820 ;; bookmarks: `bmkp-autonamed-bookmark-p' and
2821 ;; `bmkp-autonamed-this-buffer-bookmark-p'. This means that (only)
2822 ;; autonamed bookmarks are made temporary whenever they are created
2823 ;; or updated.
2824 ;;
2825 ;; The doc string for the option lists the predefined bookmark type
2826 ;; predicates, but you can use any bookmark predicates.
2827 ;;
2828 ;; * Finally, you can toggle whether *all* bookmarks become temporary
2829 ;; whenever they are created or updated, using command
2830 ;; `bmkp-toggle-autotemp-on-set', which is bound globally to `C-x p
2831 ;; x'.
2832 ;;
2833 ;; You can delete all such temporary bookmarks from the current
2834 ;; bookmark list using command `bmkp-delete-all-temporary-bookmarks'
2835 ;; (or by using `X M' to mark them in the bookmark-list display and
2836 ;; then hitting `D' to delete thems).
2837 ;;
2838 ;; In the bookmark-list display (buffer `*Bookmark List*'), temporary
2839 ;; bookmarks are indicated with the mark `X' in the same column where
2840 ;; the annotation mark `a' would otherwise appear.
2841
2842 ;;(@* "Automatic Bookmarking")
2843 ;; ** Automatic Bookmarking **
2844 ;;
2845 ;; You might or might not find automatic bookmarking useful. The
2846 ;; idea is that Emacs sets a bookmark for you automatically, whenever
2847 ;; you are idle for a given period of time (option
2848 ;; `bmkp-auto-idle-bookmark-mode-delay'). Then you can navigate
2849 ;; among those bookmarks to visit spots where you spent some time
2850 ;; (idly).
2851 ;;
2852 ;; How many such automatic bookmarks would you want? And where?
2853 ;; Bookmark+ tries to provide some user options that let you get the
2854 ;; behavior you want.
2855 ;;
2856 ;; In general, you probably do not want such bookmarks to be created
2857 ;; too often or too close together. You probably do not care about
2858 ;; the names of the bookmarks created, and you do not want to be
2859 ;; interrupted to name them. You probably want automatic bookmarking
2860 ;; to be per-buffer, but you might sometimes want to turn it on or
2861 ;; off for all buffers. You might want more than one automatic
2862 ;; bookmark on a given line, but probably not. Finally, you might or
2863 ;; might not want automatic bookmarks to be temporary (current
2864 ;; session only) or highlighted.
2865 ;;
2866 ;; Mode `bmkp-auto-idle-bookmark-mode' is a local minor mode, which
2867 ;; means that it is buffer-specific. The command of the same name
2868 ;; turns the mode on and off. When the mode is on, the minor-mode
2869 ;; indicator ("lighter") `Auto-Bmk' is shown in the mode line for the
2870 ;; buffer. You can customize this indicator (removing it, if you
2871 ;; like), using option `bmkp-auto-idle-bookmark-mode-lighter'.
2872 ;;
2873 ;; Command `bmkp-global-auto-idle-bookmark-mode' turns on the mode in
2874 ;; all buffers, that is, it is global, not local. Regardless of
2875 ;; whether you use the mode locally or globally, a bookmark is
2876 ;; created automatically only in the current buffer. That is, a
2877 ;; buffer must be current (selected) for an automatic bookmark to be
2878 ;; created there - it is not enough that the mode be enabled in the
2879 ;; buffer.
2880 ;;
2881 ;; Option `bmkp-auto-idle-bookmark-mode-set-function' defines the
2882 ;; bookmark-setting function. By default, its value is
2883 ;; `bmkp-set-autonamed-bookmark-at-line', which sets an autonamed
2884 ;; bookmark at (the beginning of) the current line. You typically
2885 ;; want bookmarks that are created automatically to be autonamed,
2886 ;; both because the name is unimportant and because setting an
2887 ;; autonamed bookmark requires no interaction on your part. But you
2888 ;; can use any setting function you like as the option value. (You
2889 ;; can always rename an autonamed bookmark later, if you want to keep
2890 ;; it and give it a meaningful name.)
2891 ;;
2892 ;; Option `bmkp-auto-idle-bookmark-min-distance' is the minimum
2893 ;; number of characters between automatic bookmark positions. If the
2894 ;; cursor is currently closer to some existing automatically created
2895 ;; bookmark, then no automatic bookmark is set at point. If you set
2896 ;; this to `nil' then there is no limit on how close the bookmarks
2897 ;; can be. (But there is only one autonamed bookmark at any given
2898 ;; position.)
2899 ;;
2900 ;; If you want the automatically created bookmarks to be temporary
2901 ;; (not saved to your bookmark file), then customize option
2902 ;; `bmkp-autotemp-bookmark-predicates' so that it includes the kind
2903 ;; of bookmarks that are set by
2904 ;; `bmkp-auto-idle-bookmark-mode-set-function'. For example, if
2905 ;; automatic bookmarking sets autonamed bookmarks, then
2906 ;; `bmkp-autotemp-bookmark-predicates' should include
2907 ;; `bmkp-autonamed-bookmark-p' or
2908 ;; `bmkp-autonamed-this-buffer-bookmark-p' (it includes both of these
2909 ;; by default). Remember that you can toggle whether a given
2910 ;; bookmark is temporary or savable, using `M-X' in the bookmark-list
2911 ;; display (buffer `*Bookmark List*').
2912 ;;
2913 ;; If you want the bookmarks to be automatically highlighted, then
2914 ;; customize option `bmkp-auto-light-when-set' to highlight bookmarks
2915 ;; of the appropriate kind. For example, to highlight autonamed
2916 ;; bookmarks set it to `autonamed-bookmark'.
2917 ;;
2918 ;; NOTE: If you use Emacs 20, then by default
2919 ;; `bmkp-auto-idle-bookmark-mode' is global rather than local. The
2920 ;; doc string tells you how to make it local instead. If you use
2921 ;; Emacs 21, then `bmkp-auto-idle-bookmark-mode' is local but there
2922 ;; is no global mode, `bmkp-global-auto-idle-bookmark-mode'. This is
2923 ;; because Emacs 21 does not support `define-globalized-minor-mode'.
2924
2925 ;;(@* "Highlighting Bookmark Locations")
2926 ;; ** Highlighting Bookmark Locations **
2927 ;;
2928 ;; You can highlight the location (destination) of a bookmark. For
2929 ;; this feature you need library `bookmark+-lit.el' in addition to
2930 ;; the other Bookmark+ libraries.
2931 ;;
2932 ;; You might never want to highlight a bookmark, or you might want to
2933 ;; highlight most or even all bookmarks, or your use of highlighting
2934 ;; might fall somewhere between. It depends on what kind of
2935 ;; bookmarks you have and how you use them. Bookmark+ lets you
2936 ;; choose. By default, no bookmarks are highlighted.
2937
2938 ;;(@* "Defining How to Highlight")
2939 ;; ** Defining How to Highlight **
2940 ;;
2941 ;; By default, autonamed bookmarks are highlighted differently from
2942 ;; non-autonamed bookmarks. Bookmark highlighting uses a style and a
2943 ;; face. The available styles are these:
2944 ;;
2945 ;; * Line - Highlight line of the bookmark position
2946 ;; * Position - Highlight character at bookmark position
2947 ;; * Line Beginning - Highlight first character on line
2948 ;; * Left Fringe - Highlight only the left fringe
2949 ;; * Left Fringe + Line - Highlight the left fringe and the line
2950 ;; * Right Fringe - Highlight only the right fringe
2951 ;; * Right Fringe + Line - Highlight the right fringe and the line
2952 ;;
2953 ;; You can customize the default styles and faces to use for
2954 ;; autonamed and non-autonamed bookmarks. You can also customize the
2955 ;; fringe bitmaps to use.
2956 ;;
2957 ;; * `bmkp-light-autonamed' (face)
2958 ;; * `bmkp-light-non-autonamed' (face)
2959 ;; * `bmkp-light-style-autonamed' (option)
2960 ;; * `bmkp-light-style-non-autonamed' (option)
2961 ;; * `bmkp-light-left-fringe-bitmap' (option)
2962 ;; * `bmkp-light-right-fringe-bitmap' (option)
2963 ;;
2964 ;; Note: A position or line highlight acts more or less like an Emacs
2965 ;; marker: it moves with the surrounding text. As you edit the text
2966 ;; in the buffer, the highlighted location can thus become out of
2967 ;; sync with the recorded position. This is normal. When you jump
2968 ;; to the bookmark its highlight is automatically repositioned to the
2969 ;; recorded location, possibly adjusted according to the the
2970 ;; surrounding context.
2971 ;;
2972 ;; In addition to the default highlighting, which you can customize,
2973 ;; you can set the highlighting for individual bookmarks and
2974 ;; particular sets of bookmarks (overriding their default
2975 ;; highlighting). These individual settings are saved as part of the
2976 ;; bookmarks themselves.
2977 ;;
2978 ;; In the bookmark list display (buffer `*Bookmark List*'):
2979 ;;
2980 ;; * `H +' - Set the highlighting for this line's bookmark
2981 ;; * `H > +' - Set the highlighting for the marked bookmarks
2982 ;;
2983 ;; Globally, you can use `M-x bmkp-set-lighting-for-bookmark' to set
2984 ;; the highlighting for a given bookmark.
2985 ;;
2986 ;; Each of these commands prompts you (with completion) for the style
2987 ;; and face to set, as well as for a condition that controls whether
2988 ;; to highlight. Each of these is optional - just hit `RET' (empty
2989 ;; input) at its prompt to skip setting it.
2990 ;;
2991 ;; The condition is an Emacs-Lisp sexp that is evaluated whenever an
2992 ;; attempt is made to highlight the bookmark. Any resulting value
2993 ;; except `:no-light' highlights the bookmark. The sexp can refer to
2994 ;; the variables `this-bookmark' and `this-bookmark-name', whose
2995 ;; values are the bookmark to be highlighted and its name,
2996 ;; respectively.
2997 ;;
2998 ;; So, for example, if you wanted to be prompted each time before
2999 ;; highlighting a certain bookmark you might set its highlighting
3000 ;; condition to a sexp such as this:
3001 ;;
3002 ;; (or (y-or-n-p (format "Highlight `%s' " this-bookmark-name))
3003 ;; :no-light)
3004 ;;
3005 ;; If you hit `n' at the prompt then `:no-light' is returned and the
3006 ;; bookmark is not highlighted.
3007 ;;
3008 ;; In the bookmark-list display, a pink-background, one-character
3009 ;; highlight is used next to each bookmark that has a highlight
3010 ;; override wrt the default. You can see what that override setting
3011 ;; is by using `C-u C-h RET' - look for the `lighting' entry in the
3012 ;; bookmark definition.
3013 ;;
3014 ;;
3015 ;;(@* "Highlighting On Demand")
3016 ;; *** Highlighting On Demand ***
3017 ;;
3018 ;; You can highlight or unhighlight a bookmark or a set of bookmarks
3019 ;; on demand.
3020 ;;
3021 ;; In the bookmark list (buffer `*Bookmark List*'):
3022 ;;
3023 ;; * `H H', `H U' - Highlight, unhighlight this line's bookmark
3024 ;;
3025 ;; * `H > H', `H > U' - Highlight, unhighlight the marked bookmarks
3026 ;;
3027 ;; Globally:
3028 ;;
3029 ;; * `C-x p C-u' - Unhighlight a highlighted bookmark at
3030 ;; point or on the same line (in that order)
3031 ;;
3032 ;; * `C-x p h', `C-x p u' - Highlight, unhighlight a bookmark in the
3033 ;; current buffer (with completion).
3034 ;;
3035 ;; * `C-x p H', `C-x p U' - Highlight, unhighlight bookmarks:
3036 ;;
3037 ;; With plain `C-u': all bookmarks
3038 ;;
3039 ;; With `C-u C-u': navigation-list bookmarks
3040 ;;
3041 ;; Otherwise, bookmarks in current buffer:
3042 ;; No prefix arg: all bookmarks
3043 ;; Prefix arg > 0: autonamed bookmarks
3044 ;; < 0: non-autonamed bookmarks
3045 ;;
3046 ;; The default bookmark for `C-x p u' is the same bookmark that is
3047 ;; unhighlighted by `C-x p C-u': a (highlighted) bookmark at point
3048 ;; (preferably) or on the same line. The latter key binding just
3049 ;; saves you having to hit `RET' to pick the default.
3050 ;;
3051 ;; When you use `C-x p h', you can use a prefix argument to override
3052 ;; both the default highlighting and any highlighting that is
3053 ;; recorded for the bookmark itself. You are prompted for the style
3054 ;; or face to use:
3055 ;;
3056 ;; * Negative arg: prompted for style
3057 ;; * Non-negative arg: prompted for face
3058 ;; * Plain `C-u': prompted for style and face
3059 ;;
3060 ;;
3061 ;;(@* "Highlighting Automatically")
3062 ;; *** Highlighting Automatically ***
3063 ;;
3064 ;; You can also highlight automatically, whenever you set (create) a
3065 ;; bookmark or jump to one. This is controlled by these options:
3066 ;;
3067 ;; * `bmkp-auto-light-when-set'
3068 ;; * `bmkp-auto-light-when-jump'
3069 ;;
3070 ;; You can choose any of these values for either option:
3071 ;;
3072 ;; * Autonamed bookmark
3073 ;; * Non-autonamed bookmark
3074 ;; * Any bookmark
3075 ;; * Autonamed bookmarks in buffer
3076 ;; * Non-autonamed bookmarks in buffer
3077 ;; * All bookmarks in buffer
3078 ;; * None (no automatic highlighting) - the default
3079 ;;
3080 ;; The first three values highlight only the bookmark being set or
3081 ;; jumped to.
3082
3083 ;;(@* "Using Highlighted Bookmarks")
3084 ;; ** Using Highlighted Bookmarks **
3085 ;;
3086 ;; Once you have highlighted bookmarks, what can you do with them?
3087 ;; Obviously, the highlighting can help you distinguish and find
3088 ;; bookmarks visually. But highlighting also serves as yet another
3089 ;; way to define sets: the highlighted vs unhighlighted bookmarks.
3090 ;;
3091 ;; Any command that operates on a set of bookmarks can be applied to
3092 ;; one or the other of these two sets. Bookmark+ defines only a few
3093 ;; such operations, but you can easily define others.
3094 ;;
3095 ;; In addition to such specific commands, you can also apply general
3096 ;; operations to the highlighted or unhighlighted bookmarks, using
3097 ;; the bookmark-list display (`*Bookmark List*'). `H S' shows only
3098 ;; the bookmarks that are currently highlighted, and `H M' marks
3099 ;; them. You can then perform any of the available bookmark-list
3100 ;; operations on them.
3101 ;;
3102 ;; Globally, you can use these keys:
3103 ;;
3104 ;; * `C-x p =' - List the bookmarks that are
3105 ;; highlighted at point. With a
3106 ;; prefix arg, show the full data.
3107 ;;
3108 ;; * `C-x j h', `C-x 4 j h' - Jump to a highlighted bookmark.
3109 ;; Only highlighted bookmarks are
3110 ;; completion candidates.
3111 ;;
3112 ;; * `C-x p C-down', `C-x p C-up' - Cycle to the next and previous
3113 ;; highlighted bookmark.
3114
3115 ;;(@* "Use Bookmark+ with Icicles")
3116 ;; ** Use Bookmark+ with Icicles **
3117 ;;
3118 ;; Icicles (http://www.emacswiki.org/cgi-bin/wiki/Icicles) enhances
3119 ;; your use of Bookmark+ in several ways.
3120 ;;
3121 ;; When jumping to a bookmark, you can narrow the completion
3122 ;; candidates to bookmarks of a particular type (e.g. Info, using
3123 ;; `C-M-i'; remote, using `C-M-@'; region, using `C-M-r'). You can
3124 ;; narrow again (and again), to another bookmark type, to get the
3125 ;; intersection (e.g. remote Info bookmarks that define a region).
3126 ;;
3127 ;; You can also narrow against different bookmark-name patterns
3128 ;; (e.g. regexps) - so-called "progressive completion". And take the
3129 ;; complement (e.g., bookmarks whose names do not match
3130 ;; `foo.*2010.*bar'). (This is not special to bookmarks; it is
3131 ;; standard Icicles practice.)
3132 ;;
3133 ;; In Icicle mode, several of the Bookmark+ keys are remapped to
3134 ;; corresponding Icicles multi-commands. A bookmark jump key thus
3135 ;; becomes a bookmarks browser. For example, `C-x j d' browses among
3136 ;; any number of Dired bookmarks.
3137 ;;
3138 ;; A single key can set a bookmark or visit bookmarks. This key is
3139 ;; whatever command `bookmark-set' would normally be bound to -
3140 ;; e.g. `C-x r m'. A prefix arg controls what it does. If negative
3141 ;; (`M--'), jump to (browse) bookmarks. Otherwise, set a bookmark
3142 ;; using `bookmark-set' (Bookmark+ version), as follows:
3143 ;;
3144 ;; * Numeric prefix arg (non-negative): No prompt. Use the buffer
3145 ;; name plus the text of the region (if active) or the current line
3146 ;; as the bookmark name. Quickest way to set a bookmark.
3147 ;;
3148 ;; * No prefix arg: same as `bookmark-set' (prompt for name).
3149 ;;
3150 ;; * Plain `C-u': same as `bookmark-set' (prompt for name, no
3151 ;; bookmark overwrite.
3152 ;;
3153 ;; During completion of a bookmark name, many features of the
3154 ;; bookmark-list display (see (@> "The Bookmark List Display")) are
3155 ;; available on the fly. Buffer `*Completions*' acts like a dynamic
3156 ;; version of `*Bookmark List*':
3157 ;;
3158 ;; * Candidates are highlighted in the `*Completions*' window
3159 ;; according to their bookmark type.
3160 ;;
3161 ;; * Candidates are Icicles multi-completions with up to three parts:
3162 ;;
3163 ;; a. the bookmark name
3164 ;; b. the bookmark file or buffer name
3165 ;; c. any tags
3166 ;;
3167 ;; You can match any or all of the parts. For example, you can
3168 ;; match bookmarks that have tags by typing this regexp:
3169 ;;
3170 ;; C-M-j . * C-M-j S-TAB
3171 ;;
3172 ;; Each `C-M-j' inserts `^G\n', which is `icicle-list-join-string',
3173 ;; the string used to join the parts. This regexp says, "match the
3174 ;; completion candidates that have all three parts (two join
3175 ;; strings)", hence some tags.
3176 ;;
3177 ;; You can turn off the use of multi-completion candidates for
3178 ;; subsequent commands, so only bookmark names are used, by hitting
3179 ;; `M-m' in the minibuffer. You can think of this as similar to
3180 ;; using `M-t' in `*Bookmark List*' to toggle showing file names.
3181 ;; You can make not showing files and tags the default behavior by
3182 ;; customizing `icicle-show-multi-completion-flag'.
3183 ;;
3184 ;; * You can sort completion candidates using the Bookmark+ sort
3185 ;; orders. Use `C-,' to cycle among sort orders.
3186 ;;
3187 ;; * You can use Icicles candidate-help keys (`C-M-RET', `C-M-down',
3188 ;; etc.) to get detailed information about the current bookmark
3189 ;; candidate. `C-u C-M-RET' shows the complete, internal info
3190 ;; defining the bookmark. And without doing anything, summary info
3191 ;; about the current candidate is available in the mode line of
3192 ;; buffer `*Completions*'.
3193 ;;
3194 ;; * You can use Icicles candidate-action keys (`C-RET', `C-mouse-2',
3195 ;; `C-down', etc.) to visit any number of bookmarks. For example,
3196 ;; holding down `C-down' cycles among the current bookmark
3197 ;; candidates, opening each in turn.
3198 ;;
3199 ;; * You can use `S-delete' to delete the bookmark named by the
3200 ;; current candidate. You can delete any number of bookmarks this
3201 ;; way, during a single invocation of a bookmark command.
3202 ;;
3203 ;; * You can define Icicles sets of bookmarks, persistent or not, and
3204 ;; act on their members in various ways.
3205 ;;
3206 ;; During file-name completion, you can do any of the following on
3207 ;; the fly:
3208 ;;
3209 ;; * Jump to one or more file bookmarks, using `C-x m'.
3210 ;;
3211 ;; * Create one or more autofile bookmarks, using `C-x a a'.
3212 ;;
3213 ;; * Add tags to one or more files (autofile bookmarks), using `C-x a
3214 ;; +'.
3215 ;;
3216 ;; * Remove tags from one or more files (autofile bookmarks), using
3217 ;; `C-x a -'.
3218
3219 ;;(@* "If you use Emacs 20 and Also a More Recent Version")
3220 ;; ** If you use Emacs 20 and Also a More Recent Version **
3221 ;;
3222 ;; This section pertains to you *ONLY* in the rare case that you use
3223 ;; both Emacs 20 and a later version, and you share the same bookmark
3224 ;; file or bookmark-list display state file between the versions.
3225 ;;
3226 ;; By default starting with Emacs 21, Bookmark+ uses bookmark names
3227 ;; that are propertized with the full bookmark information, in order
3228 ;; to let you use multiple bookmarks with the same bookmark name. An
3229 ;; example of this is having two autofile bookmarks for files with
3230 ;; the same name in different directories.
3231 ;;
3232 ;; When you save the bookmark list (`bookmark-alist') or a full
3233 ;; snapshot of the bookmark-list display state (e.g., using command
3234 ;; `bmkp-bmenu-define-full-snapshot-command'), these propertized
3235 ;; names are saved.
3236 ;;
3237 ;; However, Emacs 20 cannot read a serialized version of the bookmark
3238 ;; list if it has such propertized names (the property value is a
3239 ;; list that contains the propertized string, hence circular) - it
3240 ;; will raise a `read' error. To avoid this, when Bookmark+ in Emacs
3241 ;; 20 saves bookmarks or a full snapshot of the bookmark-list display
3242 ;; state, it unpropertizes the bookmark names. You can read the
3243 ;; resulting files in any Emacs version.
3244 ;;
3245 ;; But if you happen to save bookmark information using a later
3246 ;; version of Emacs (e.g. Emacs 23) and you then read that recorded
3247 ;; state using Emacs 20, the read will fail. If this happens then
3248 ;; you will need to re-save the affected file(s) using a later Emacs
3249 ;; version. In the later Emacs version:
3250 ;;
3251 ;; 1. `M-x set-variable bmkp-propertize-bookmark-names-flag nil',
3252 ;; to stop using propertized bookmark names.
3253 ;; 2. `C-x p e' or `C-x r l' to display the bookmark list.
3254 ;; 3. `g', to refresh the display.
3255 ;; 4. `S' to save the bookmark list.
3256 ;; 5. `M-x bmkp-save-menu-list-state', to save the display state.
3257 ;;
3258 ;; You will now be able to use your bookmarks in Emacs 20 again.
3259 ;;
3260 ;; If you will often be going back and forth between Emacs 20 and a
3261 ;; later version, then you may prefer to simply turn off the use of
3262 ;; propertized bookmark names, to avoid the hassle mentioned above.
3263 ;; You can do that by customizing user option
3264 ;; `bmkp-propertize-bookmark-names-flag' to nil.
3265 ;;
3266 ;; Be aware, however, that if you do that you will not be able to
3267 ;; take full advantage of Bookmark+ features such as autofile
3268 ;; bookmarks, which require the ability to have multiple bookmarks
3269 ;; with the same name. See (@> "Autofile Bookmarks").
3270
3271 ;;(@* "Bookmark Compatibility with Vanilla Emacs (`bookmark.el')")
3272 ;; ** Bookmark Compatibility with Vanilla Emacs (`bookmark.el') **
3273 ;;
3274 ;; Bookmark+ is generally compatible with GNU Emacs versions 20
3275 ;; through 23.
3276 ;;
3277 ;; 1. All bookmarks created using any version of vanilla Emacs
3278 ;; (library `bookmark.el') continue to work with Bookmark+.
3279 ;;
3280 ;; 2. All bookmarks created using Bookmark+ will work with all Emacs
3281 ;; versions (20-23), provided you use Bookmark+ to access them.
3282 ;;
3283 ;; 3. Most bookmarks created using Bookmark+ will not interfere with
3284 ;; the behavior of vanilla Emacs, versions 21-23. The new
3285 ;; bookmark types are simply ignored by vanilla Emacs. For
3286 ;; example:
3287 ;;
3288 ;; - A bookmark with a region is treated like a simple position
3289 ;; bookmark: the destination is the region start position.
3290 ;;
3291 ;; - A Gnus bookmark does not work; it is simply ignored.
3292 ;;
3293 ;; However, there are two cases in which Bookmark+ bookmarks will
3294 ;; raise an error in vanilla Emacs:
3295 ;;
3296 ;; * You cannot use non-file (e.g. buffer-only) bookmarks with any
3297 ;; version of vanilla Emacs.
3298 ;;
3299 ;; * You cannot use any bookmarks created using Bookmark+ with
3300 ;; vanilla Emacs 20.
3301 ;;
3302 ;; The Emacs bookmark data structure has changed from version to
3303 ;; version. Bookmark+ always creates bookmarks that have the most
3304 ;; recent structure (Emacs 23). As is the case for any bookmarks
3305 ;; that have the Emacs 23 structure, these bookmarks will not work
3306 ;; in vanilla Emacs 20 (that is, without Bookmark+).
3307 ;;
3308 ;; Bottom line: Use `bookmark+.el' to access bookmarks created using
3309 ;; `bookmark+.el'.
3310
3311 ;;(@* "New Bookmark Structure")
3312 ;; ** New Bookmark Structure **
3313 ;;
3314 ;; The bookmark data structure, variable `bookmark-alist', has been
3315 ;; enhanced to support new bookmark types. For a description of this
3316 ;; enhanced structure, use `C-h v bookmark-alist'.
3317 ;;
3318 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3319 ;;
3320 ;; This program is free software; you can redistribute it and/or modify
3321 ;; it under the terms of the GNU General Public License as published by
3322 ;; the Free Software Foundation; either version 3, or (at your option)
3323 ;; any later version.
3324 ;;
3325 ;; This program is distributed in the hope that it will be useful,
3326 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
3327 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3328 ;; GNU General Public License for more details.
3329 ;;
3330 ;; You should have received a copy of the GNU General Public License
3331 ;; along with this program; see the file COPYING. If not, write to
3332 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
3333 ;; Floor, Boston, MA 02110-1301, USA.
3334 ;;
3335 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3336 ;;
3337 ;;; Code:
3338
3339 ;; You need not load this file. It contains only documentation.
3340
3341 (provide 'bookmark+-doc)
3342
3343 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3344 ;;; bookmark+-doc.el ends here
3345