EmacsWiki: bookmark+-doc.el (original) (raw)
;;; bookmark+-doc.el - Documentation for package Bookmark+.
;;
;; Filename: bookmark+-doc.el
;; Description: Documentation for package Bookmark+
;; Author: Drew Adams
;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
;; Copyright (C) 2000-2024, Drew Adams, all rights reserved.
;; Created: Fri Sep 15 07:58:41 2000
;; Last-Updated: Sun Sep 15 18:28:37 2024 (-0700)
;; By: dradams
;; Update #: 15423
;; URL: https://www.emacswiki.org/emacs/download/bookmark%2b-doc.el
;; Doc URL: https://www.emacswiki.org/emacs/BookmarkPlus
;; Keywords: bookmarks, bookmark+, placeholders, annotations, search,
;; info, url, eww, w3m, gnus
;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x, 24.x, 25.x, 26.x
;;
;; Features that might be required by this library:
;;
;; None
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;; Documentation for the Bookmark+ package, which provides
;; extensions to standard library bookmark.el'. ;; ;; The Bookmark+ libraries are these: ;; ;;
bookmark+.el' - main (driver) library
;; bookmark+-mac.el' - Lisp macros ;;
bookmark+-lit.el' - (optional) code for highlighting bookmarks
;; bookmark+-bmu.el' - code for the
Bookmark List' (bmenu)
;; bookmark+-1.el' - other required code (non-bmenu) ;;
bookmark+-key.el' - key and menu bindings
;;
;; bookmark+-doc.el' - documentation (comment-only - this file) ;;
bookmark+-chg.el' - change log (comment-only file)
;;
;; The documentation includes how to byte-compile and install
;; Bookmark+. It is also available in these ways:
;;
;; 1. From the bookmark list (C-x x e' or
C-x r l'):
;; Use ?' to show the current bookmark-list status and general ;; help, then click link
Doc in Commentary' or link Doc on the ;; Web'. ;; ;; 2. From the Emacs-Wiki Web site: ;; https://www.emacswiki.org/emacs/BookmarkPlus. ;; ;; 3. From the Bookmark+ group customization buffer: ;;
M-x customize-group bookmark-plus', then click link
;; Commentary'. ;; ;; (The commentary links in #1 and #3 work only if put you this ;; library,
bookmark+-doc.el', in your load-path'.) ;; ;; More Bookmark+ description below. ;; ;; To report Bookmark+ bugs:
M-x customize-group bookmark-plus'
;; and then follow (e.g. click) the link Send Bug Report', which ;; helps you prepare an email to me. ;; ;; ;; ****** NOTE ****** ;; ;; On 2010-06-18, I changed the prefix used by package Bookmark+ ;; from
bookmarkp-' to bmkp-'. THIS IS AN INCOMPATIBLE CHANGE. ;; I apologize for the inconvenience, but the new prefix is ;; preferable for a number of reasons, including easier ;; distinction from standard
bookmark.el' names.
;;
;; This change means that YOU MUST MANUALLY REPLACE ALL
;; OCCURRENCES of bookmarkp-' by
bmkp-' in the following
;; places, if you used Bookmark+ prior to this change:
;;
;; 1. In your init file (~/.emacs') or your
custom-file', if
;; you have one. This is needed if you customized any
;; Bookmark+ features.
;;
;; 2. In your default bookmark file, bookmark-default-file' ;; (
/.emacs.bmk'), and in any other bookmark files you might
;; have.
;;
;; 3. In your /.emacs-bmk-bmenu-state.el').
;;
;; 4. In your *Bookmark List*' state file, ;;
bmkp-bmenu-state-file' (`*Bookmark List*' commands file, ;;
bmkp-bmenu-commands-file' (~/.emacs-bmk-bmenu-commands.el'), ;; if you have one. ;; ;; You can do this editing in a virgin Emacs session (
emacs
;; -Q'), that is, without loading Bookmark+.
;;
;; Alternatively, you can do this editing in an Emacs session
;; where Bookmark+ has been loaded, but in that case you must
;; TURN OFF AUTOMATIC SAVING of both your default bookmark file
;; and your *Bookmark List*' state file. Otherwise, when you ;; quit Emacs your manually edits will be overwritten. ;; ;; To turn off this automatic saving, you can use
M-' and
;; `C-M-' in buffer *Bookmark List*' (commands ;;
bmkp-toggle-saving-bookmark-file' and
;; bmkp-toggle-saving-menu-list-state' - they are also in the ;;
Bookmark+' menu).
;;
;; Again, sorry for this inconvenience.
;;(@> "Index")
;;
;; Index
;; -----
;;
;; If you have library linkd.el' and Emacs 22 or later, load ;;
linkd.el' and turn on linkd-mode' now. It lets you easily ;; navigate around the sections of this doc. Linkd mode will ;; highlight this Index, as well as the cross-references and section ;; headings throughout this file. You can get
linkd.el' here:
;; https://www.emacswiki.org/emacs/download/linkd.el.
;;
;; (@> "Documentation")
;; (@> "Installing Bookmark+")
;; (@> "Bookmark+ Load Order and Option bookmark-default-file'") ;; (@> "Bookmark+ Features") ;; (@> "Bookmark Basics") ;; (@> "Different Types of Jump Commands") ;; (@> "Bookmark Annotations") ;; (@> "Bookmark Tags") ;; (@> "Bookmark Tags Can Have Values") ;; (@> "Hierarchical Structures of Bookmarks?") ;; (@> "Function, Sequence, Variable-List,... Bookmarks") ;; (@> "Little Persistent Named Nothings") ;; (@> "Editing Bookmarks") ;; (@> "Bookmark Records: What A Bookmark Looks Like") ;; (@> "Bookmark-List Views - Saving and Restoring State") ;; (@> "Quitting Saves the Bookmark-List State") ;; (@> "State-Restoring Commands and Bookmarks") ;; (@> "Bookmarking without Visiting the Target") ;; (@> "Bookmarking a File or a URL") ;; (@> "Bookmarking the Marked Files in Dired") ;; (@> "Bookmarking Compilation, Grep, and Occur Hits") ;; (@> "Bookmarking Files That You Cannot Visit with Emacs") ;; (@> "Opening Bookmarks Using Windows File Associations") ;; (@> "Autofile Bookmarks") ;; (@> "A Type-Aware
find-file'")
;; (@> "Tagging Files")
;; (@> "Using Multiple Bookmark Files")
;; (@> "Bookmark Files For Bookmarks with Specific Tags")
;; (@> "Bookmark-File Bookmarks")
;; (@> "The Bookmark List Display")
;; (@> "Jumping To Bookmarks from the Bookmark List Display")
;; (@> "Tag Commands and Keys")
;; (@> "Tags: Sets of Bookmarks")
;; (@> "Open Dired for the Marked File Bookmarks")
;; (@> "Marking and Unmarking Bookmarks")
;; (@> "Filtering Bookmarks (Hiding and Showing)")
;; (@> "Only Visible Bookmarks Are Affected")
;; (@> "Omitting Bookmarks from Display")
;; (@> "Sorting Bookmarks")
;; (@> "Bookmarks for Specific Files or Buffers")
;; (@> "Cycling, Navigation List")
;; (@> "The Bookmark Navigation List")
;; (@> "Cycling the Navigation List")
;; (@> "Cycling Dynamic Sets of Bookmarks")
;; (@> "Cycling in the Current File/Buffer")
;; (@> "Autonamed Bookmarks - Easy Come Easy Go")
;; (@> "Temporary Bookmarks")
;; (@> "Temporary Bookmarking Mode")
;; (@> "Making Bookmarks Temporary")
;; (@> "Automatic Bookmarking")
;; (@> "Automatic Bookmarking Using a Hook")
;; (@> "Automatic Idle-Period Bookmarking")
;; (@> "Automatic Info Bookmarking")
;; (@> "Highlighting Bookmark Locations")
;; (@> "Defining How to Highlight")
;; (@> "Highlighting On Demand")
;; (@> "Highlighting Automatically")
;; (@> "Using Highlighted Bookmarks")
;; (@> "Bookmark Links")
;; (@> "Org Mode Links that Jump To Bookmarks")
;; (@> "Bookmark Menus")
;; (@> "Use Bookmark+ with Icicles")
;; (@> "Bookmark Compatibility with Vanilla Emacs (`bookmark.el')")
;; (@> "New Bookmark Structure")
;;(@* "Documentation")
;;
;; Documentation
;; -------------
;;
;;(@* "Installing Bookmark+")
;; ** Installing Bookmark+ **
;;
;; The main Bookmark+ library is bookmark+.el'. The other required ;; libraries are
bookmark+-mac.el', bookmark+-bmu.el', ;;
bookmark+-1.el', and bookmark+-key.el'. If you want to be able ;; to highlight bookmarks then you will also need library ;;
bookmark+-lit.el'. I recommend that you byte-compile all of the
;; libraries, after loading the source files (in particular, load
;; bookmark+-mac.el'). ;; ;; Put the directory of these libraries in your
load-path' and add
;; this to your init file (~/.emacs):
;;
;; (require 'bookmark+)
;;
;; That will load all of the Bookmark+ libraries. If you do not care
;; about bookmark highlighting then simply do not put
;; bookmark+-lit.el' in your
load-path'.
;;
;; By default (see option bmkp-crosshairs-flag'), when you visit a ;; bookmark that has no region it is highlighted temporarily using ;; crosshairs, for easy recognition. (This temporary highlighting is ;; independent of the highlighting provided by
bookmark+-lit.el'.)
;;
;; For this optional crosshairs feature you also need library
;; crosshairs.el', which in turn requires libraries
col-highlight',
;; hl-line',
hl-line+', and vline'. Library
hl-line' comes with
;; vanilla Emacs. The others are available from the Emacs Wiki web
;; site: https://www.emacswiki.org/. You also need Emacs 22 or later
;; for this feature.
;;
;;
;;(@* "Bookmark+ Load Order and Option bookmark-default-file'") ;; *** Bookmark+ Load Order and Option
bookmark-default-file' ***
;;
;; Standard option bookmark-default-file' defines the default ;; location of your bookmark file. Bookmark+ does not change the ;; value. You can change the value, of course, either by customizing ;; it (recommended) or using Lisp code (including in your init file). ;; ;; However, the value of
bookmark-default-file' is used when you
;; load Bookmark+ to initialize some other variables, in particular
;; option bmkp-last-as-first-bookmark-file' and internal variable ;;
bmkp-current-bookmark-file'.
;;
;; This means that if you modify bookmark-default-file' in your init ;; file, and you want your new value to be take into account by ;; Bookmark+, then modify it before you load Bookmark+. ;; ;; Be aware also that another library that you load might, itself, ;; load Bookmark+, in which case you will for the same reason want to ;; load that library after you have modified
bookmark-default-file'.
;; An example of this is Icicles, which loads Bookmark+ if Bookmark+
;; is in your load-path'. ;; ;; In general, with Bookmark+ I recommend that you simply set option ;;
bookmark-default-file' once and for all at the outset, preferably
;; by customizing it. You can use bmkp-switch-bookmark-file-create' ;; at any time to switch to a different bookmark file - it is bound ;; to
C-x x L'. You can also invoke it in your init file, provided
;; Bookmark+ has already been loaded.
;;
;; See Also: (@> "Using Multiple Bookmark Files")
;;(@* "Bookmark+ Features")
;; ** Bookmark+ Features **
;;
;; Here is an overview of some of the features that Bookmark+
;; provides. Some of these are detailed in other sections, below.
;;
;; * Richer bookmarks. They record more. They are more accurate.
;;
;; - An optional bookmark annotation is user-supplied text that is
;; saved as part of the bookmark. You can use any text you
;; like, and you can use it for any purpose you like. In
;; Bookmark+, the mode for viewing and editing a bookmark
;; annotation is Org mode, by default.
;;
;; - In addition, Bookmark+ lets you optionally use a separate
;; file, URL, or bookmark to annotate any bookmark. Accessing
;; ("showing") such an external annotation visits its
;; destination. So for example, you can use bookmarks to one or
;; more Org files to annotate one or more bookmarks. The
;; annotation saved with the bookmark itself just specifies the
;; destination. See (@> "Bookmark Annotations").
;;
;; - You can tag bookmarks, a la del.icio.us. In effect, tags
;; define bookmark sets. A bookmark can have any number of
;; tags, and multiple bookmarks can have the same tag. You can
;; sort, show/hide, or mark bookmarks based on their tags.
;;
;; - Bookmark+ tags can be more than just names. They can be
;; full-fledged user-defined attributes, with Emacs-Lisp objects
;; as their values.
;;
;; - You can have multiple bookmarks with the same name. This is
;; particularly useful for autofile bookmarks, which are
;; bookmarks that have the same name as their target files or
;; directories. They give you the effect of using files or
;; directories themselves as bookmarks. In particular, they let
;; you, in effect, tag files and directories.
;; See (@> "Autofile Bookmarks") and (@> "Tagging Files").
;;
;; (In vanilla Emacs you can also, in theory, have multiple
;; bookmarks with the same name. But you cannot really use them
;; in any practical way. Vanilla Emacs cannot distinguish among
;; them: the most recent one shadows all others with the same
;; name.)
;;
;; - Bookmarks record the number of times you have visited them
;; and the time of the last visit. You can sort, show/hide, or
;; mark bookmarks based on this info.
;;
;; - You can combine bookmarks, to make composite, or sequence,
;; bookmarks. Invoking a sequence bookmark invokes each of its
;; component bookmarks in turn. A component bookmark can itself
;; be a sequence bookmark.
;;
;; - You can bookmark a region of text, not just a position. When
;; you jump to a bookmark that records a region, the region is
;; activated (see option bmkp-use-region'). (Region activation ;; is not supported for Gnus bookmarks.) ;; ;; You can define your own region handler for bookmarks that ;; record regions. (This is in addition to being able to define ;; bookmark handlers.) Use option
bmkp-handle-region-function'
;; for this. As one example, command
;; bmkp-region-jump-narrow-indirect-other-window' binds the ;; option to a function that narrows the targeted region in a ;; cloned indirect buffer. (You need library ;;
narrow-indirect.el' for this command.)
;;
;; - Bookmarks are relocated better than for vanilla Emacs when
;; the contextual text changes.
;;
;; * Additional ways to bookmark.
;;
;; - You can bookmark the file or URL named at point (or any other
;; file or URL), without first visiting it.
;;
;; - You can bookmark the targets of the hits in a compilation
;; buffer or an occur' buffer, without first visiting them. ;; ;; - You can bookmark all of the marked files in Dired at once. ;; ;; * Additional types of bookmarks. ;; ;; Bookmark+ adds over 70 types of bookmark. (You can see what they ;; all are by invoking function
bmkp-types-alist'.) Here are the
;; main ones:
;;
;; - Autofile bookmarks. You can bookmark a file without visiting
;; it or naming the bookmark. The bookmark name is the same as
;; the file name (nondirectory part). You can have multiple
;; such bookmarks with the same name, to bookmark files with the
;; same name but in different directories.
;;
;; - Dired bookmarks. You can bookmark a Dired buffer, recording
;; and restoring its ls' switches, which files are marked, ;; which subdirectories are inserted, and which (sub)directories ;; are hidden. ;; ;; - Dired-tree bookmarks. A set of Dired bookmarks that ;; represent a directory hierarchy and are opened together. ;; ;; - Bookmark-list bookmarks. You can bookmark the current state ;; of buffer
Bookmark List' - a list of bookmarks. Jumping
;; to such a bookmark restores the recorded sort order,
;; markings, filter, title, and omit list.
;; See (@> "Omitting Bookmarks from Display").
;;
;; - Bookmark-file bookmarks. You can bookmark a bookmark file.
;; Jumping to such a bookmark loads the bookmarks in the file.
;; See (@> "Bookmark-File Bookmarks").
;;
;; - Desktop bookmarks. You can bookmark the current Emacs
;; desktop, as defined by library desktop.el' - use command ;;
bmkp-set-desktop-bookmark' (C-x x K'). You can "jump" to a ;; desktop bookmark (that is, restore its saved desktop). A ;; desktop includes: ;; ;; - Some global variables. To exclude variables normally ;; saved, see option
bmkp-desktop-no-save-vars'.
;; - The current set of buffers and their associated files.
;; For each: its mode, point, mark, & some local variables.
;;
;; If option bmkp-desktop-jump-save-before-flag' is non-
nil',
;; and if the current desktop was made current by jumping to a
;; bookmark, then it is saved before jumping to the next
;; desktop. If you want to save the last desktop jumped to when
;; you quit Emacs, then add bmkp-desktop-save-as-last' to ;;
kill-emacs-hook'.
;;
;; - Gnus bookmarks. You can bookmark a Gnus article, a URL, a
;; PDF file (DocView), a UNIX manual page (from the output of
;; Emacs command man' or
woman'), an image, or a piece of
;; music.
;;
;; - Non-file (buffer) bookmarks. You can bookmark a buffer that
;; is not associated with a file.
;;
;; - Function bookmarks. A bookmark can represent a Lisp
;; function, which is invoked when you "jump" to the bookmark.
;;
;; - Sequence (composite) bookmarks. A bookmark can represent a
;; sequence of other bookmarks.
;;
;; - Keyboard-macro bookmarks, bookmarks for sets of keyboard
;; macros, and sequence bookmarks that combine another bookmark
;; with a keyboard macro.
;;
;; - Lisp variable bookmarks. A bookmark can represent a set of
;; variables and their values.
;;
;; - Snippet bookmarks. Select some some text and give it a
;; (bookmark) name. Then copy it to the kill-ring' anytime, in ;; any Emacs session. ;; ;; - Icicles search-hits bookmarks. (You need library Icicles to ;; use this feature.) During Icicles search you can use
C-x
;; C-M->' to save the current set of completion candidates
;; (search hits matching your current input) as an Icicles
;; search-hits bookmark. During a later Icicles search you can
;; retrieve those search hits saved in the bookmark, by using
;; C-x C-M-<
. You can add to (instead of replacing) the
;; current set of hits with hits retrieved from a bookmark using
;; C-x C-<'. This is the only way you can "jump" to such a ;; bookmark. ;; ;; In particular, note that you can use the following kinds of ;; bookmarks to quickly switch among different projects (sets of ;; bookmarks): Dired, Dired tree, bookmark-list, bookmark-file, ;; and desktop bookmarks. ;; ;; * Type-specific jump commands. ;; ;; - When you want to jump to a bookmark of a specific type ;; (e.g. Dired), you can use a command that offers only such ;; bookmarks as completion candidates. ;; ;; - You can also use generic command
bmkp-jump-to-type', bound
;; to C-x j :'. It prompts you for the bookmark type, then ;; offers only bookmarks of that type as completion candidates. ;; ;; * Define your own new bookmark types. ;; ;; Just as for vanilla Emacs, you can easily define your own ;; bookmark types, by defining a function to create its record, ;; using function
bookmark-make-record', or by binding variable
;; bookmark-make-record-function' for a given context. ;; ;; You can also make jumping to a new type of bookmarks ;; type-specific, usable with
bmkp-jump-to-type' (C-x j :') or ;; with your own type-specific jump command. ;; ;; For that, you need to do this: ;; ;; 1. Define a function
bmkp-TYPE-alist-only', which returns an
;; alist of bookmarks that are only of your new TYPE, for use
;; with bookmark-completing-read'. The alist should have the ;; same form as
bookmark-alist'. (And you can use your alist
;; for more than just completion.)
;;
;; 2. Evaluate (bmkp-define-history-variables)', to add a history ;; variable for your type, again, for use with ;;
bookmark-completing-read'.
;;
;; You can use macro bmkp-define-type-from-hander' to define a ;; simple bookmark type that's based only on a given handler. You ;; pass it the TYPE name and HANDLER name as arguments. It does #1 ;; and #2 above, plus it defines: ;; ;; * A predicate,
bmkp-TYPE-bookmark-p', which returns non-nil if
;; its bookmark argument has the given HANDLER.
;;
;; * A command to show only bookmarks of TYPE in Bookmark List.
;; (Macro bmkp-define-show-only-command' is used to do this.) ;; ;; (Remember that to use any of the Bookmark+ macros directly ;; you'll need to load library
bookmark+-mac.el'.)
;;
;; * Extensive menus.
;;
;; - In the *Bookmark List*' display, a
mouse-3' popup menu has
;; actions for the individual bookmark that you point to when
;; you click the mouse.
;;
;; - In the *Bookmark List*' display, a complete menu-bar menu, ;;
Bookmark+', is available. The same menu is available on
;; C-mouse-3'. It has submenus
Jump To', Mark',
Omit',
;; Show',
Sort', Tags',
Highlight' (needs library
;; bookmark+-lit.el), and
Define Command'.
;;
;; - The vanilla Bookmarks' menu, which is typically a submenu of ;; the menu-bar
Edit' menu, is modified by adding several items
;; from the Bookmark+' menu, including submenus
Jump To',
;; Tags', and
Highlight'.
;;
;; - Bookmark+ adds two items to the menu bar Edit' menu: ;; ;; . Save the active region text as a bookmark. ;; . Jump to the bookmark to copy the text to the kill ring, so ;; you can then yank it anywhere. ;; ;; - Some modes provide a
Bookmarks Here' menu-bar submenu with
;; items to access bookmarks for the current file/buffer.
;; Display of this menu is controlled by option
;; bmkp-add-bookmarks-here-menu-flag' (
nil' by default
;; because computing the menu can take a little time).
;;
;; * Improvements for the bookmark-list display.
;;
;; This is buffer *Bookmark List*', aka the bookmark "menu list" ;; (a misnomer), which you display using
C-x x e' (or C-x r l'). ;; See (@> "The Bookmark List Display"). ;; ;; - The last display state is saved (by default), and is restored ;; the next time you show the list. (Tip: Use the bookmark list ;; as your "Home" page at Emacs startup.) ;; ;; - You can save the current bookmark-list state at any time and ;; return to it later. There are a few ways to do this, ;; including bookmarking the list itself. ;; See (@> "Bookmark-List Views - Saving and Restoring State"). ;; ;; - Marking/unmarking is enhanced. It is similar to Dired's. ;; ;; - You can easily mark or show different classes of bookmarks. ;; ;; - Faces distinguish bookmarks by type. ;; ;; - You can sort bookmarks in many ways. You can easily define ;; your own sort orders, even complex ones. ;; ;; - You can regexp-search (
M-a') or query-replace (M-q') the ;; targets (destination file or buffers) of the marked ;; bookmarks, in the current bookmark-list sort order. For ;; Emacs 23 and later, you can even search incrementally (
M-s a
;; C-s', or M-s a C-M-s' for regexp). ;; ;; - You can use
M-d >' to open Dired for just the local file
;; bookmarks that are marked (>'). ;; ;; - If you use Emacs on Microsoft Windows, you can open bookmarks ;; according to Windows file associations. (You will also need ;; library
w32-browser.el'.)
;;
;; - You can use (lax) completion when you set a bookmark using
;; C-x r m' (
bmkp-bookmark-set-confirm-overwrite'), choosing
;; from existing bookmarks for the same buffer. This makes it
;; easy to update a nearby bookmark (e.g. relocate it). With a
;; numeric prefix argument (or if there are no bookmarks for the
;; buffer), you can choose from all bookmarks.
;;
;; - You can edit a bookmark: its name and file name/location, its
;; tags, or its complete defining internal Lisp record.
;;
;; - The mode line shows the number of bookmarks that are marked
;; (>'), flagged for deletion (
D'), tagged (t'), temporary ;; (
X'), annotated (a'), and modified (unsaved) (
'). It
;; also shows the current sort order.
;;
;; For each of the number indicators (e.g., the number marked):
;;
;; If the current line has the indicator (e.g. >') and there ;; are other lines with the same indicator that are listed after ;; the current line, then the indicator shows
N/M', where N is
;; the number indicated through the current line and M is the
;; total number indicated. Otherwise, it shows just N'. ;; ;; This feature is available starting with Emacs 24.3. (For ;; prior versions I removed it because Emacs bug #12867 can ;; cause Emacs to crash.) ;; ;; * Multiple bookmark files. ;; ;; - Although vanilla Emacs lets you load different bookmark ;; files, it does not support this feature well, and the ;; behavior can even be contradictory. With Bookmark+ you can ;; easily (a) switch among alternative bookmark files or (b) ;; load multiple files into the same session, accumulating their ;; bookmark definitions. The last file you used is the default ;; when you choose a file to switch to, so it is easy to go back ;; and forth between two bookmark files. ;; See (@> "Using Multiple Bookmark Files"). ;; ;; * Dedicated keymaps as prefix keys. ;; ;; - Prefix
C-x x' is used for bookmark keys, in general. The
;; vanilla keys on prefix C-x r' are still available also, but ;; that prefix is shared with register commands, making it less ;; convenient for bookmarks. Using
C-x x' lets you focus on
;; bookmarks.
;;
;; - Prefix C-x x c' is for setting various kinds of bookmarks. ;; ;; - Prefixes
C-x j' and C-x 4 j' (for other-window) are used ;; for bookmark jump commands. Again, a dedicated prefix key ;; helps you focus on one kind of action (jumping). ;; ;; All of these prefix keys correspond to prefix-map variables, so ;; you need not use these particular prefixes. You can bind these ;; maps to any prefix keys you want. These are the maps, together ;; with their predefined bindings. ;; ;;
bookmark-map' - C-x x' ;;
bmkp-set-map' - C-x x c' ;;
bmkp-tags-map' - C-x x t' ;;
bmkp-jump-map' - C-x j' ;;
bmkp-jump-other-window-map' - C-x 4 j' ;; ;; Those are the prefix keys that are available by default. To ;; change them, just customize these user options, each of which ;; is a list of the key sequences to use as prefix key. ;; ;; -
bmkp-bookmark-map-prefix-keys' - default: ("^Xp")
;; - bmkp-jump-map-prefix-keys' - default: ("^Xj") ;; -
bmkp-jump-other-window-map-prefix-keys' - default: ("^X4j")
;;
;; (^X' here is actually the Control-X character.) ;; ;; Keymaps
bmkp-set-map' and bmkp-tags-map' are always on ;;
bookmark-map', whatever prefix keys it is on. So if, for
;; example, you customize bmkp-bookmark-map-prefix-keys' to be ;; ("^Xp" [f9]) then the keys in
bmkp-set-map' have both prefix
;; C-x x c' and prefix
c'.
;;
;; In addition to keys on Bookmark+ keymaps, Bookmark+ binds some
;; mode-specific bookmarking commands in some other modes: Occur,
;; Compilation (including Grep), Buffer-menu, EWW, Gnus, Info,
;; Man, Woman, W3M, and Dired (if you use library Dired+'). ;; These keys let you set or jump to bookmarks specific to the ;; modes. ;; ;; * Helpful help. ;; ;; - Information about individual bookmarks. ;; ;; . Anywhere in Emacs,
C-x h M' (command
;; bmkp-describe-bookmark') describes any bookmark. With a ;; prefix argument, it shows you the full information that ;; defines it (internal form). ;; ;; . With the cursor on a highlighted bookmark,
C-x x ?' shows
;; the same description, and a prefix argment has the same
;; effect (show internal form).
;;
;; . Hovering your mouse over a highlighted bookmark shows the
;; same description, in a tooltip. Actually, you can
;; customize the description using option
;; bmkp-tooltip-content-function'. The default value is ;;
bmkp-bookmark-description', which describes the bookmark.
;; A value of bmkp-annotation-or-bookmark-description', for ;; example, shows the bookmark annotation if there is one, or ;; the full description if not. ;; ;; . In the bookmark list,
C-h RET' (or C-h C-RET') describes ;; the bookmark under the cursor. The description is as ;; complete as possible - for example, for an image-file ;; bookmark the complete EXIF image metadata is shown. (This ;; is only for Emacs 22 and later, and only if you have ;; command-line tool
exiftool' installed. See standard Emacs
;; library image-dired.el' for more information about ;;
exiftool'.)
;;
;; And again, a prefix arg (C-u C-h RET') means show the full ;; (internal) bookmark information. ;; ;;
C-h >' shows the same information that C-h RET' shows, ;; but for all of the marked bookmarks, in the current sort ;; order. That is, it describes each of the marked bookmarks. ;; ;;
C-down' and C-up' move the cursor down and up a line, ;; respectively, but they also show the description of the ;; bookmark corresponding to the new cursor location. This is ;; a quick way to cycle among bookmark descriptions, in the ;; current sort order. ;; ;; - General Bookmark+ documentation. ;; ;; . Anywhere in Emacs,
M-x bmkp-bmenu-mode-status-help' shows
;; detailed information about the current state of the
;; bookmark list. Click button Doc in Commentary' or button ;;
Doc on the Web' to access the complete documentation.
;;
;; (Use button Customize' to customize all Bookmark+ ;; faces and options.) ;; ;; . In the bookmark list,
?' and C-h m' are the same as
M-x
;; bmkp-bmenu-mode-status-help'. (C-h m' in the bookmark ;; list does not show you info about minor modes. If you want ;; that, use
M-x describe-mode'.)
;;
;; . In the bookmark-plus' group customization buffer (
M-x
;; customize-group bookmark-plus'), click button Commentary'. ;; ;; . From the Emacs-Wiki Web site, ;; https://www.emacswiki.org/emacs/BookmarkPlus. ;; ;; - It is easy to recognize orphaned and invalid bookmarks. ;; ;; . Invalid bookmarks are shown in a special face in the ;; bookmark-list display. ;; ;; . You can easily mark all of the orphaned bookmarks, that is, ;; those whose recorded files have been renamed or deleted. ;; You can then relocate or delete those bookmarks. ;; ;; - It is easy to recognize modified (i.e., unsaved) bookmarks. ;; They are marked with
'. Likewise, bookmarks that have tags
;; (marked with t'); bookmarks that have annotations (
a'); and
;; bookmarks that are temporary (X'), meaning that they will ;; not be saved. ;; ;; * Jump-destination highlighting. ;; ;; - When you jump to a bookmark, the destination (position) is ;; highlighted temporarily using crosshairs, to make it stand ;; out. Option
bmkp-crosshairs-flag' controls this, and this
;; feature is available only if you also use library
;; crosshairs.el'. ;; ;; * Visual bookmarks (highlighting). ;; ;; - You can highlight the locations of bookmarks, either ;; automatically or on demand. You control what kind of ;; highlighting, if any, is used for which bookmarks. This ;; feature requires that you have library
bookmark+-lit.el' in
;; your load-path' (it will then be loaded by
bookmark+.el).
;;
;; * Better, user-configurable bookmark-name defaults.
;;
;; See the doc strings of command bookmark-set' (Bookmark+ ;; version) and options
bmkp-new-bookmark-default-names' and
;; bmkp-default-bookmark-name'. ;; ;; * Synergy with
Icicles'.
;;
;; - `Icicles' works with Bookmark+ to provide enhanced bookmark
;; jumping (visiting), setting, and help. It gives you a
;; bookmark browser, and lets you bookmark and tag files on the
;; fly. See (@> "Use Bookmark+ with Icicles") and
;; https://www.emacswiki.org/emacs/Icicles.
;;(@* "Bookmark Basics")
;; ** Bookmark Basics **
;;
;; Bookmark+ builds on vanilla Emacs bookmarks. If you are familiar
;; with the latter, then you can skip this section, which mostly
;; reviews the former. However, this section also introduces some
;; Bookmark+ concepts and features that are detailed in other
;; sections.
;;
;; In Emacs bookmarking these three things are different but related:
;;
;; 1. the bookmark list
;; 2. the bookmark file
;; 3. the bookmark-list display (buffer *Bookmark List*', aka the ;; bookmark "menu list", a misnomer) ;; ;; It is important to keep these three straight and understand their ;; differences in practice, in particular, when they do and do not ;; represent the same set of bookmarks. ;; ;; #1 is in memory. It is the current set of bookmarks. When you ;; add, rename, delete, etc. a bookmark, this list is updated. ;; ;; #2 is on disk. It is a persistent record of a set of bookmarks. ;; ;; The bookmark list (#1) is the current value of internal variable ;;
bookmark-alist'. The bookmark file (#2) can be anywhere. Its
;; default filename is the value of user option
;; bookmark-default-file'. ;; ;; The bookmark list is typically initialized from the bookmark file ;; - referred to as loading your bookmarks, but you can also create ;; bookmarks (adding them to the list) without ever saving them to ;; disk. ;; ;; The bookmark list can be saved to the bookmark file - referred to ;; as saving your bookmarks - either automatically or on demand. But ;; it is not necessarily saved. Even if it has been saved in the ;; past, that does not mean that at any given time the bookmark list ;; corresponds exactly to the bookmark file. ;; ;; The list and the file can often become out of sync. In an Emacs ;; session, the bookmark list rules. After an Emacs session, the ;; bookmark file rules (it is all there is). You can use
C-x x L'
;; (bmkp-switch-bookmark-file-create') to sync (revert) the list to ;; reflect the file - just accept the default value, "switching" to ;; the same file. ;; ;; The bookmark-list display (#3) is a snapshot view of the bookmarks ;; in the bookmark list. As such, what you see there reflects the ;; state of the bookmark list at some point in time. So here again, ;; the two, list and display, can be out of sync. Hitting
g' in the
;; bookmark-list display refreshes it to accurately reflect the
;; current bookmark list (#1). Some other operations in the display
;; also keep it synced with the list.
;;
;; Using a prefix argument (C-u g') syncs the display (#3) and the ;; list (#1) to the file (#2). This can be useful when some other ;; process (e.g., another Emacs session) updates the bookmark file or ;; when you want to abandon changes to the current bookmark list and ;; any of the current bookmarks. Outside the bookmark-list display, ;; you can use command
bmkp-revert-bookmark-file' to do this.
;;
;; You can load different bookmark files, either adding their
;; bookmarks to those already in the current bookmark list or
;; replacing them.
;;
;; The most important takeaway from this section is that #1 (list),
;; #2 (file), and #3 (display) can be out of sync, and they often
;; are. And that can be useful.
;;
;; Until now, everything said in this section is true of vanilla
;; Emacs as well as Bookmark+. Bookmark+ adds some flexibility
;; regarding the use of multiple bookmark files, and it can save the
;; last state of the bookmark-list display for later reuse.
;;
;; The saved state of the display is restored when you show the
;; display after quitting it (q') in the same session or quitting ;; Emacs, but only if the bookmark file whose location it recorded is ;; the same as the current bookmark file. ;; ;; It would not make sense to display a completely different set of ;; bookmarks from those that are currently loaded. The display must ;; always reflect the current bookmark list (even if it sometimes ;; reflects it imperfectly, because it is a snapshot). So if the ;; bookmark file that is loaded is different from the one that was ;; recorded for the display state, the recorded state is ignored. ;; ;; ;;(@* "Automatic Saving") ;; *** Automatic Saving *** ;; ;; Before getting into the topic of automatic saving, let me say this ;; clearly once: BACK UP YOUR BOOKMARK FILE(S)! ;; ;; (Bookmark+ creates backups when your bookmark file is saved. ;; Until bug #12507 is fixed, vanilla Emacs does not.) ;; ;; I recommend that you set option
bookmark-version-control' to t', ;; so that you get numbered backups. ;; ;; If you do use numbered backups then you might also want to ;; customize option
delete-old-versions', setting the value to t', ;; so that you are not bothered by this prompt each time bookmarks ;; are saved: ;; ;; Delete excess backup versions of <YOUR-INIT-FILE>? (y or n) ;; ;; See also nodes
Backup Names' and Backup Deletion' in the Emacs ;; manual. ;; ;; User option
bookmark-save-flag' controls whether and how often to
;; automatically save the bookmark list to the bookmark file, thus
;; syncing the two. You can toggle this option using M-~' in the ;; bookmark-list display. ;; ;; In the bookmark-list display, you can tell whether individual ;; bookmarks have been modified since the last save: they are marked ;; with
*'. I believe that this indication is robust and accurate
;; (if not, please report a bug), but a word of caution: do not
;; depend on it. The only way to be sure that your bookmarks have
;; been saved is to save them. ;-)
;;
;; Is there a way to unmodify a single bookmark that you have
;; changed? No, not unless it is the only one you modified. If you
;; revert to the bookmarks as last saved, then all changes to all
;; bookmarks (including addition and removal of bookmarks) are lost.
;; If you want to work carefully when making multiple changes, then
;; save any modifications you are sure of before you move on to
;; others. If only one bookmark is modified then reverting to the
;; bookmark file effectively unmodifies that bookmark.
;;
;; When you consult the doc for option bookmark-save-flag' you see ;; that besides values of
nil' and t', meaning off and on, it can ;; have a value that is the number of bookmark modifications to allow ;; before automatically saving. If the value is 10, for instance, ;; then the 11th modification triggers automatic saving. ;; ;; But a modification means any change to any bookmark. Typically, ;; you are more interested in considering all of the changes caused ;; by a given command as one modification. Why? Suppose you use a ;; command such as
T > +' (bmkp-bmenu-add-tags-to-marked'), which ;; adds a set of tags to each of the marked bookmarks. Even if there ;; have been no other modifications since you last saved bookmarks, ;; if there are more marked bookmarks than your setting of ;;
bookmark-save-flag' then automatic saving will kick in in the
;; middle of the command. Some of the bookmarks with the added tags
;; will be automatically saved. And that does not give you an
;; opportunity to cancel the changes (e.g., by quitting without
;; saving).
;;
;; This is the reason for option bmkp-count-multi-mods-as-one-flag', ;; whose default value is
t', which means count all of a sequence of
;; modifications together as one modification, as far as
;; `bookmark-save-flag' is concerned.
;;(@* "Different Types of Jump Commands")
;; ** Different Types of Jump Commands **
;;
;; When you jump to a bookmark, you can use completion to specify the
;; bookmark name. bookmark-jump' and
bookmark-jump-other-window',
;; bound to C-x j j' and
C-x 4 j j', are general commands. Their
;; completion candidates include all of your bookmarks. With
;; Bookmark+ you can easily have a large number of bookmarks.
;;
;; To provide more specificity, Bookmark+ provides many different
;; bookmark jump commands. If you want to jump to a bookmark of a
;; specific type, such as Info, you can use a Bookmark+ command that
;; is specific to bookmarks of that type: only those bookmarks are
;; completion candidates.
;;
;; There are thus type-specific commands: bmkp-dired-jump', ;;
bmkp-info-jump', and so on, bound to C-x j d',
C-x j i', and so
;; on. There are also commands to jump to bookmarks for the current
;; buffer or for particular buffers or files
;; (see (@> "Bookmarks for Specific Files or Buffers")).
;;
;; All bookmark jump commands are bound to keys that have the prefix
;; C-x j'. There is an other-window version of most jump commands, ;; and it is bound to the same key as the same-window command, except ;; the prefix is
C-x 4 j', not C-x j'. For instance, ;;
bmkp-dired-jump-other-window' is bound to C-x 4 j d'. ;; ;; (In the bookmark-list display, you can use just
j' instead of
;; C-x 4 j', and just
J' (uppercase) instead of C-x j'.) ;; ;; More precisely, the bookmark jump commands are on the prefix maps ;;
bmkp-jump-map' and bmkp-jump-other-window-map', which have the ;; default bindings
C-x j' and C-x 4 j'. You can bind these maps ;; to any keys you like, by customizing options ;;
bmkp-jump-map-prefix-keys' and
;; bmkp-jump-other-window-map-prefix-keys'. ;; ;; If you do not remember the different type-specfic bindings, you ;; can use commands
bmkp-jump-to-type' and
;; bmkp-jump-to-type-other-window' (
C-x j :' and C-x 4 j :'). ;; They work for any type, prompting you first for the type, then for ;; a bookmark of that type (only). ;; ;; There are several commands for jumping to a bookmark with tags. ;; The completion candidates can be those bookmarks that have all ;; tags in a given set, some tags in a given set, all tags matching a ;; regexp, or some tags matching a regexp. You are prompted for the ;; set of tags or the regexp to match. ;; ;; These commands all have the prefix key
C-x j t'. The suffix key
;; is *' for "all" and
+' for "some". The regexp-matching commands
;; precede the suffix key with %'. For example,
C-x j t % +' jumps
;; to a bookmark you choose that has one or more tags that match the
;; regexp you input.
;;
;; There are some type-specific jump commands for bookmarks with
;; tags. The key sequences for these include a key that indicates
;; the bookmark type, after the t' indicating tags. For example, ;; commands for jumping to a file or directory bookmark having ;; certain tags use the prefix
C-x j t f' (f' for file). Similar ;; commands for autofile bookmarks have prefix
C-x j t a' (a' for ;; autofile). ;; ;; For example,
C-x j t f % *' jumps to a file or directory bookmark
;; you choose, where all of its tags match a regexp, and C-x j t a ;; +' finds a file tagged with at least one of the tags you input. ;; ;; In addition to the ordinary autofile "jump" commands, there are ;;
find-file' versions: they read a file name using
;; read-file-name', instead of completing a bookmark name. - see ;; (@> "Autofile Bookmarks"). These commands are available starting ;; with Emacs 22. ;; ;; Bookmark names are global. File names are not; that is, the ;; nondirectory portion is not. Suppose you have two similar ;; directories with some like-named files, perhaps tagged in similar ;; ways. Imagine image files of your vacations organized in ;; different directories by year. It is sometimes useful to narrow ;; your focus to the file bookmarks in one directory. ;; ;; Commands such as
bmkp-file-this-dir-jump' (C-x j . f') offer as ;; completion candidates only bookmarks for files and subdirs in the ;; current directory (
default-directory'). For tags, there are
;; equivalent commands. For example, C-x j t . % *' is the same as ;;
C-x j t f % *', but the destinations are limited to files in the
;; current directory. All of the "this-dir" file jump commands are
;; bound to the same keys as the general file jump commands, but with
;; .' instead of
f'.
;;
;; Remember that Bookmark+ collects lots of commands on only a few
;; predefined prefix keys, primarily as a mnemonic device. Nothing
;; requires you to use the long key sequence C-x j t f % *' to visit ;; a file that has a given set of tags. It is expected that you will ;; bind short key sequences to commands that you use often. ;; ;; The
C-x j' and C-x 4 j' bindings are global. In addition, in ;; some modes
j' is bound to the corresponding type-specific jump
;; command. For example, in Info mode, j' is bound to ;;
bmkp-info-jump'. (Dired is an exception here: J' is used ;; instead of
j', since j' is already taken for
dired-goto-file'.)
;; These commands are also added to the mode's menu-bar menu.
;;
;; In Dired mode, C-j' is bound to a special Dired-specific jump ;; command,
bmkp-dired-this-dir-jump', whose destinations all use
;; the current directory (default-directory'). The aim of
C-j' is
;; not to change directories but to change to a different set of
;; Dired markings, switches, inserted subdirectories, or hidden
;; subdirectories for the same Dired directory.
;;
;; In addition to the predefined bookmark types, which you can use as
;; described above, you can define a "type"-specific jump command for
;; any set of bookmarks. That is, you can use any specific set of
;; bookmarks as the completion candidates for a new jump command.
;; Such a set is really only a pseudo-type: the actual bookmarks can
;; each be of any type.
;;
;; You could use this feature, for example, to define a jump command
;; for the bookmarks that belong to a given project.
;;
;; One way to define such a command is to first mark the bookmarks
;; that you want to be the completion candidates, then use C-c C-j' ;; (command
bmkp-bmenu-define-jump-marked-command') in the bookmark
;; list.
;;
;; The *Bookmark List*' display defines a set of bookmarks, even ;; without markings. So does each bookmark of type bookmark list, ;; that is, a bookmark corresponding to a particular
Bookmark
;; List' display state - see
;; (@> "State-Restoring Commands and Bookmarks").
;;
;; You can capture the set of bookmarks corresponding to a *Bookmark ;; List*' display for use in navigation, that is, as the current ;; "navigation list". Navigation here includes jumping and cycling ;; - see (@> "Cycling, Navigation List"). ;; ;; To capture in the navigation list the bookmarks corresponding to ;; either the current
Bookmark List' display or a bookmark-list
;; bookmark, use C-x x B', which is bound to command ;;
bmkp-choose-navlist-from-bookmark-list'. To then jump to a
;; bookmark from such a navigation list, use C-x j N' or
C-x 4 j N'
;; (bmkp-jump-in-navlist' or
bmkp-jump-in-navlist-other-window').
;;(@* "Bookmark Annotations")
;; ** Bookmark Annotations **
;;
;; With Bookmark+ you can bookmark many kinds of Emacs object.
;; Bookmarks record locations - that is their primary purpose. They
;; can also record annotations: general free-text descriptions of
;; your choosing. An annotation is thus metadata that is associated
;; with a bookmark. You can use it for any purpose you like.
;;
;; "Annotation" is arguably not the best name for what this is or
;; does. But that's the name vanilla Emacs uses for it, so Bookmark+
;; does too.
;;
;; Command bookmark-show-annotation' shows an annotation in ;; read-only mode. You can use
C-x C-q' in the annotation buffer to
;; switch to edit mode (and back again).
;;
;; You can use command bookmark-edit-annotation' or ;;
bmkp-annotate-bookmark' anywhere to edit the annotation for a
;; bookmark. For bookmark-edit-annotation', you can choose among ;; the bookmarks that already have annotations. With a prefix arg, ;; you can choose any bookmark (and so create an annotation). Using ;;
bmkp-annotate-bookmark' is the same as using
;; bookmark-edit-annotation' with a prefix arg. ;; ;; The annotation edit buffer starts with some text that isn't saved ;; as part of the annotation. It shows some editing instructions, ;; the user name, system name, and date+time of the current edit. ;; ;; In the annotation edit buffer, make your changes and then use
C-c
;; C-c' to save the result. Use C-x C-k' if you don't want to save ;; the changes. You can also use
C-x C-q' and then y' to confirm ;; reverting the changes. ;; ;; Non-
nil' user option bookmark-automatically-show-annotations' ;; means that a bookmark's annotation is popped up whenever you jump ;; to the bookmark. If the non-
nil' value is edit' then the ;; annotation buffer is in edit mode; if it is any other non-
nil'
;; value then the buffer is in show (read-only) mode.
;;
;; In the *Bookmark List*' display, bookmarks with annotations are ;; marked by an
a' character to the left of the bookmark name. You
;; can use a a' to show the annotation for the bookmark on the ;; current line. You can use
a e' to create an annotation or edit
;; an existing annotation for it. You can use a >' to edit ;; annotations for all of the marked bookmarks. You can use
a A' to
;; show a list of the names and annotations of all annotated
;; bookmarks.
;;
;; A bookmark annotation is stored as part of the bookmark itself.
;; For this reason, you typically want to keep the text fairly short.
;; In Bookmark+, the mode for viewing and editing a bookmark
;; annotation is Org mode, by default. (To change the mode used,
;; customize option bmkp-annotation-modes-inherit-from'.) ;; ;; You can obtain the effect of using a longer annotation, and some ;; other advantages as well, by using an "annotation forward" in the ;; annotation text. This is short text that serves only as a pointer ;; to an external file, URL, or another bookmark. ;; ;; Whenever you show the annotation of a bookmark (via
a a' in the
;; *Bookmark List*' display,
bookmark-show-annotation', or
;; bookmark-automatically-show-annotations') and the annotation ;; contains such a pointer (only one such is used), the effect is to ;; visit the pointer's destination. That is, showing the annotation ;; goes to the forward destination, instead of showing the annotation ;; text stored with the bookmark. (You can still see the latter, by ;; editing the annotation.) ;; ;; So for example, you can use bookmarks to one or more Org files to ;; annotate (provide notes about, or metadata for) one or more other ;; bookmarks. For example, set a bookmark at some place in an Info ;; manual, then write your own notes about that Info content in an ;; Org file, bookmark that Org-file destination, and use that as a ;; forward destination in your bookmark to that Info location. ;; ;; You create an annotation forward for a bookmark by using one of ;; these forms as the annotation text. ;; ;; bmkp-annot-url: "FILE" ;; bmkp-annot-url: "URL" ;; bmkp-annot-url: "BOOKMARK" ;; ;; * FILE is an absolute file name. Forwarding to it uses ;;
find-file-other-window'.
;; * URL is a URL. Forwarding to it uses browse-url'. ;; * BOOKMARK is the name of a bookmark in the current bookmark ;; alist. Forwarding just jumps to it. ;; ;; The double-quote characters are necessary here, so that you can ;; include characters such as
SPC' in the name. The text must be on
;; the first line of the annotation (not counting the commented
;; instruction lines). It can be preceded only by whitespace.
;;
;; You can include other text in the annotation, after the external
;; destination specification, and you can see or edit it when you
;; edit the annotation (e.g., a e' in buffer
Bookmark List').
;; But it is ignored when the annotation is only shown (e.g., a a'). ;; ;; In the
Bookmark List' display, M-down' and
M-up' move the
;; cursor down and up a line, respectively, but they also show the
;; annotation, if any, of the bookmark at the new cursor location.
;;(@* "Bookmark Tags")
;; ** Bookmark Tags **
;;
;; In addition to annotating bookmarks with arbitrary metadata,
;; Bookmark+ bookmarks can also be tagged, as a way to organize them,
;; which also means as a way to organize the objects that are
;; bookmarked.
;;
;; By "tagging" and "tag" in this context is meant associating
;; keywords or other text with an object, typically in order to
;; classify or characterize it. Tags are metadata about an object.
;; This notion of tagging is sometimes called "delicious" tagging
;; after the Web site www.delicious.com that popularized it
;; (https://en.wikipedia.org/wiki/Delicious_(website)'). ;; ;; Be aware that there is another notion of "tag" associated with ;; Emacs: that involving Emacs tags files, which record the locations ;; of function, variable, etc. definitions in source files. There is ;; no relation between the two notions of "tag". ;; ;; A bookmark tag is a string (or a cons whose car is a string - see ;; (@> "Bookmark Tags Can Have Values")). You can add as many tags ;; as you like to any bookmark, and multiple bookmarks can have the ;; same tag(s). In fact, that's the whole idea behind using them for ;; organizing. ;; ;; This feature is unrelated to the fact that bookmarks record ;; locations and are useful for navigating. You can, if you want, ;; use bookmarks to tag files in various ways purely for purposes of ;; organizing them (e.g. into projects), whether or not you ever use ;; the bookmarks as a way to visit them. ;; ;; For example, if you use
Dired+' (library dired+.el'), then you ;; can use
M-b' (diredp-do-bookmark') in Dired to create an ;; autofile bookmark for each of the marked files and subdirectories ;; in the Dired buffer. Even if you never use those bookmarks for ;; navigating to their targets, you can use them with tags to ;; organize the targets, and thus operate on subsets of the marked ;; files and subdirectories. ;; ;; And if you use libraries
Dired+' and highlight.el' then ;; autofiles are highlighted specially in Dired, and the highlighting ;; indicates whether the file is tagged. ;; ;; By default, you create bookmarks without tags and add tags to them ;; later. If you prefer, you can customize option ;;
bmkp-prompt-for-tags-flag' to non-nil' so that you are prompted ;; to add tags immediately whenever you set (create or update) a ;; bookmark. ;; ;; There are also some commands, such as
bmkp-tag-a-file' (C-x x t ;; + a') and
bmkp-untag-a-file' (C-x x t - a'), that always prompt ;; for tags to add or remove. (In general, the key
a' is used in
;; key sequences for autofile bookmarks.)
;;
;; When you are prompted to enter a tag, you type some text then hit
;; RET'. If you want to include a newline character in the tag ;; itself, use
C-q C-j' (C-j' is the newline character). You can ;; use
C-q' this way to enter any character. If you do use complex
;; strings as tags then you might prefer to simply edit a bookmark's
;; tags in a separate buffer. You can do that using C-x x t e' (or ;;
T e' in the bookmark-list display).
;;
;; Whenever you are prompted for a tag you can use completion. The
;; completion candidates available are the tag names defined by
;; option bmkp-tags-for-completion'. The default value of this ;; option is
current', meaning use only the tags from the bookmarks
;; in the current bookmark list as candidates. You can customize the
;; option to include specific tags or the tags from bookmarks in
;; specific bookmark files.
;;
;; You can use command bmkp-list-all-tags' to list all of the tags ;; defined by option
bmkp-tags-for-completion' or, with a numeric
;; prefix argument, only the tags corresponding to the current
;; bookmark file. You can list the tag names only or (using a
;; non-negative prefix arg) show the full tag definitions, which
;; include any associated tag values (see (@> "Bookmark Tags Can Have Values")
;; for information about tag values).
;;
;; To make tags more useful, Bookmark+ provides lots of commands:
;; commands for adding, removing, copying, pasting, and renaming
;; tags; commands for jumping to bookmarks with particular sets of
;; tags; and commands for marking or unmarking (in buffer *Bookmark ;; List*') bookmarks that are tagged in various ways. ;; ;; Most commands pertaining to tags are by default on prefix key
C-x
;; p t' - use C-x x t C-h' to see them. In buffer
Bookmark
;; List', commands pertaining to tags are on prefix key T' - use
T
;; C-h' to see them. And remember that you can use C-h >' to ;; describe all of the marked bookmarks, in the current sort order. ;; The bookmark descriptions include the tags. ;; ;; When combined with other Bookmark+ commands (e.g. search, ;; query-replace) that apply to the marked bookmarks in the ;;
Bookmark List' window, you can really do quite a lot using
;; bookmark tags. Use your imagination!
;;
;; See Also:
;;
;; * (@> "Bookmark Records: What A Bookmark Looks Like")
;; * (@> "Bookmarking the Marked Files in Dired")
;; * (@> "Opening Bookmarks Using Windows File Associations")
;; * (@> "Tag Commands and Keys")
;;
;;
;;(@* "Bookmark Tags Can Have Values")
;; *** Bookmark Tags Can Have Values ***
;;
;; Bookmark tags are simply names (strings) when you create them.
;; Nearly all of the predefined operations that use tags use these
;; names: sorting, marking, jumping, and so on. But you can in fact
;; add an associated value to any tag. This means that a tag can act
;; just like an object attribute or property: it can be a name/value
;; pair.
;;
;; To add a value to a tag that has none, or to change the current
;; value of a tag, you use command bmkp-set-tag-value', which is ;; bound to
T v' in the bookmark list and bound to C-x x t v' ;; globally. You are prompted for the bookmark, the tag, and the new ;; value. ;; ;; A tag value can be a number, symbol, string, list, vector, and so ;; on. It can be as complex as you like. It can be any Emacs-Lisp ;; object that has read syntax, that is, that is readable by the Lisp ;; reader. (Everything that is saved as part of a bookmark must be ;; readable; otherwise, your bookmark file could not be read ;; (loaded).) ;; ;; Because tag values can be pretty much anything, you are pretty ;; much on your own when it comes to making use of them. Bookmark+ ;; does not provide predefined functions for using tag values. In ;; general, tag values are something you will use with home-grown ;; Lisp code for your own purposes. ;; ;; However, you can easily make some interactive use of tag values ;; with little effort. You can, for example, define a predicate that ;; tests whether a bookmark has a tag value that satisfies some ;; property (e.g. is a number greater than 3.14159265358979), and ;; then you can use command
bmkp-bmenu-mark-bookmarks-satisfying' to
;; mark those bookmarks.
;;
;; Tags that have the prefix "bmkp-" are reserved - do not name your
;; own tags using this prefix.
;;
;; Currently, "bmkp-jump" is the only predefined bookmark tag. You
;; can give this tag a value that is a function - it is called
;; whenever the tagged bookmark is visited. Any Lisp-readable
;; function value is allowed: a symbol or a lambda expression.
;;
;; For example, to display Hello!' when a bookmark is visited you ;; can use this: ;; ;; T v bmkp-jump RET (lambda () (message "Hello!")) ;; ;; The function that is the value of a "bmkp-jump" tag is called just ;; after the the standard hook
bookmark-after-jump-hook' is invoked.
;; You can use this tag to invoke functions that are specific to
;; individual bookmarks; bookmarks can thus have their own, extra
;; jump functions.
;;
;;
;;(@* "Hierarchical Structures of Bookmarks?")
;; *** Hierarchical Structures of Bookmarks? ***
;;
;; You can use tags to organize sets of bookmarks in various ways.
;; But what about a simple, hierarchical (tree-shaped) structure like
;; the one that you use for bookmarks in a web browser? You can get
;; a similar effect with Bookmark+ by just using a tag-naming
;; convention such as this:
;;
;; vacation/
;; vacation/2017/
;; vacation/2017/winter/
;; vacation/2017/winter/photos/
;; vacation/2017/summer/
;; vacation/2017/summer/photos/
;; vacation/2018/
;; ...
;;
;; You need not tag any bookmarks with any particular part of such a
;; pseudo-hierarchy. For example, you might tag some bookmarks with
;; vacation/2017/winter/ and some with vacation/2017/winter/photos/,
;; without bothering to have any that are tagged with just vacation/
;; or just vacation/2017/.
;;
;; You are not limited to a single tree. You can have a tag such as
;; vacation/2017/winter/ and a tag such as work/projects/2017/alpha/,
;; without any need for those to have a common ancestor.
;;
;; How can you use such a tagging scheme?
;;
;; When you jump to a bookmark using a command that asks for tags,
;; such as C-x j t +' (
bmkp-some-tags-jump'), you can use
;; completion. So you can, for example, type vac TAB' to show all ;; of your vacation tags (in
Completions'), and drill down,
;; completing more, to pick whichever particular vacation tag you're
;; interested in. This is similar to traversing a web-browser
;; tree-like bookmarks menu. But jump commands that use tags let you
;; match any number of tags at the same time, not just one.
;;
;; Completion against the set of existing tags is also available when
;; you add tags to a bookmark. And if option
;; bmkp-prompt-for-tags-flag' is non-
nil' then you are prompted to
;; add tags whenever you create or update a bookmark. But unlike the
;; case for web-browser bookmark creation, classifying a bookmark
;; when you create it or update it is optional. You can always add
;; tags later, or not at all.
;;
;; Such a purely conventional, pseudo-hierarchy might sound like a
;; silly hack, but it is at least as quick to use as is adding a
;; bookmark to your tree of browser bookmarks. And it is more
;; useful, because the organization is more flexible and you can have
;; multiple, independent hierarchies.
;;
;; The tagging scheme just described can help you keep track of
;; things, even though it is very simple. There is nothing special
;; about it. You might come up with other conventions for
;; classifying tags, which you find more convenient or more powerful.
;; And remember that tags can be more than just names. They give you
;; the full power of Lisp values - do with them whatever you like.
;;(@* "Function, Sequence, Variable-List,... Bookmarks")
;; ** Function, Sequence, Variable-List,... Bookmarks **
;;
;; Bookmarks are typically thought of only as recorded locations.
;; Invoking a bookmark, called "jumping" to it, traditionally means
;; just visiting its location. Bookmark+ looks at bookmarks in a
;; more general way than that. A bookmark is a shortcut of some kind
;; - nothing more. It is typically persistent, but it need not be
;; (see (@> "Temporary Bookmarks")).
;;
;; A given type of bookmark is defined by its handler function, which
;; can do anything you like. We've already seen the examples of
;; region bookmarks, which restore the active region, and Dired
;; bookmarks, which restore Dired markings, switches, inserted
;; subdirectories, and hidden (sub)directories.
;;
;; A "function bookmark" simply invokes some function - any function.
;; You can, for instance, define a window or frame configuration and
;; record the configuration as a bookmark. Then jump to the bookmark
;; to switch contexts. (You can also bookmark a desktop and jump to
;; that.)
;;
;; Function bookmarks might not seem too interesting, since there are
;; other ways to invoke functions in Emacs. But the other features
;; of Bookmark+ combine with this feature. You can, for instance,
;; tag function bookmarks.
;;
;; And you can combine them, invoking the functions sequentially.
;; This is a particular case of using a "sequence bookmark", which
;; simply records a sequence of bookmarks. The bookmarks in a
;; sequence can be of any kind, including other sequence bookmarks.
;;
;; Command bmkp-make-function-bookmark' (
C-x x c F') creates a
;; function bookmark - you give it a function symbol or a lambda
;; expression.
;;
;; A function bookmark can invoke a keyboard macro instead of a
;; function. With a prefix argument, bmkp-make-function-bookmark' ;; creates a function bookmark from the last keyboard macro. Jumping ;; to the bookmark executes the keyboard macro. A bookmark is thus ;; one way to make a keyboard macro persistent. ;; ;; If you provide a prefix argument to the bookmark jump command or ;; key that invokes a function bookmark, it is passed along to the ;; function. If the bookmark invokes a keyboard macro then the ;; prefix argument determines how many times the macro is invoked. ;; ;; The most general way to create or update a sequence bookmark is ;; using command
bmkp-set-sequence-bookmark' (C-x x c s'). You are ;; prompted for the sequence bookmark name and the names of the ;; bookmarks that form its sequence and are thus invoked by it ;; sequentially. ;; ;; If the sequence bookmark already exists then a prefix argument ;; determines whether the bookmarks you name are added to the ;; existing sequence or replace it, and if added, whether before or ;; after the bookmarks already in the sequence. ;; ;; Command
bmkp-wrap-bookmark-with-last-kbd-macro' (C-x x c C-k') ;; returns a sequence bookmark that invokes a bookmark you name and ;; then invokes the last keyboard macro. You are prompted for the ;; names of both bookmarks. If the sequence bookmark does not yet ;; exist then it is created. (The bookmark to be added to the ;; sequence need not exist yet, and it is not created by adding its ;; name to the sequence.) ;; ;; If you enter the same name for the sequence bookmark and the ;; bookmark to wrap with the keyboard macro, then the macro is simply ;; added to that (sequence) bookmark. ;; ;; For example, if you enter
my-seq' for both of the
;; bmkp-wrap-bookmark-with-last-kbd-macro' prompts, then the last ;; keyboard macro is added to sequence bookmark
my-seq'. Bookmark
;; my-seq' need not exist yet, in which case it is created, with the ;; keyboard macro as its only member bookmark. ;; ;; If the bookmark to add to the sequence is itself a different ;; (existing) sequence bookmark, then its member bookmarks are added ;; to the sequence being updated (or created), either before or after ;; its existing members, according to the prefix arg (which is passed ;; to
bmkp-set-sequence-bookmark').
;;
;; Command bmkp-bmenu-make-sequence-from-marked' creates a sequence ;; bookmark from the marked bookmarks in the bookmark-list display, ;; in their current order. ;; ;; If you use library
Dired+' (dired+.el') then you can use command ;;
diredp-do-bookmark-dirs-recursive' to create a Dired bookmark for
;; the current Dired buffer and each of its marked subdirectories.
;; Each of those subdirectories is handled similarly, and so on,
;; recursively. This command also creates a sequence bookmark that
;; includes all of these Dired bookmarks, so that it represents a
;; tree (hierarchy) of Dired buffers that are opened together. This
;; provides an alternative to inserting all of the relevant
;; subdirectories into the same Dired buffer. With a prefix arg, all
;; of the descendent Dired buffers are included, whether or not they
;; are marked.
;;
;; You can also create a function bookmark directly from a keyboard
;; macro, using command bmkp-set-kmacro-bookmark'. And you can save ;; the current set of keyboard macros as a bookmark, using command ;;
bmkp-set-kmacro-list-bookmark' - jumping to it restores all of
;; the macros'.
;;
;; A variable-list bookmark saves and restores the values of a set of
;; variables. Command bmkp-set-variable-list-bookmark' prompts you ;; for the variables to include in the list and then sets the ;; bookmark. Command
bmkp-jump-variable-list' (C-x j v') restores ;; the recorded variable values for the bookmark's buffer. You can ;; also create variable-list bookmarks non-interactively, using ;; function
bmkp-create-variable-list-bookmark'.
;;
;; If you use library zones.el', then you can move among multiple ;; restrictions (narrowings) in a buffer. The restrictions are ;; stored in buffer-local variable
zz-izones'. Command
;; bmkp-set-izones-bookmark' bookmarks this value for the current ;; buffer. Jumping to such a bookmark restores the saved ring/stack ;; of restrictions. ;; ;; ;;(@* "Little Persistent Named Nothings") ;; *** Little Persistent Named Nothings *** ;; ;; OK, so a bookmark need not "go" anywhere. Function, sequence, ;; variable-list, and some other kinds of bookmarks have no real ;; "location" to move to or restore. But the bookmarks talked about ;; so far at least have an associated action: you can "jump" to them, ;; even if "jump" can mean a arbitrary action that might have nothing ;; to do with reaching a destination. ;; ;; You can also have a *non-invokable* bookmark, that is, one that ;; you cannot jump to. This is a bookmark whose handler is the ;; function
ignore', which does nothing.
;;
;; What's the point of that? To record something persistently,
;; without needing to manage the file(s) you record it in, and to be
;; able to access that something by name.
;;
;; As an example, library Isearch+ provides one such use case. It
;; lets you interactively add, modify, and remove Isearch filter
;; predicates on the fly, providing more power and flexibility in
;; searching.
;;
;; (A filter predicate is a function that accepts the current
;; search-hit limits as arguments. If it returns nil' then that ;; search hit is excluded from searching; otherwise it is included.) ;; ;; You can also, on the fly, encapsulate the current suite of filter ;; predicates as a new filter predicate. That is, you can manipulate ;; a complex sequence of filters as a single predicate, using a ;; simple name. And you can save the definition of that new ;; predicate in a file, so you can use it again in future Emacs ;; sessions. ;; ;; Alternatively, you can just bookmark the search predicate. The ;; data saved in the bookmark is the suite of filters that is the ;; advised value of
isearch-filter-predicate' at the time of
;; bookmarking.
;;
;; Then, in a future Emacs session, while Isearching you can hit a
;; key and enter the bookmark name (with completion), to apply that
;; suite of filters again.
;;
;; Bookmarking is easier than defining a new predicate and bothering
;; with a file to save it in. This is the kind of thing that
;; bookmarks are for: persistently saving named bits of data for
;; later retrieval by name.
;;
;; Because the saved data in this case (the filter definition) has no
;; use outside the context of searching, there is no way to invoke it
;; - no jump action. Its handler is ignore'. ;; ;; You can apply all Bookmark+ features to non-invokable bookmarks: ;; sort, edit, tag - whatever. Use Bookmark+ to organize them, even ;; if you cannot invoke them. ;; ;; Non-invokable bookmarks are shown using face
bmkp-no-jump' in the
;; bookmark-list display.
;;
;; It is also possible for a bookmark to have a handler other than
;; ignore', so that it is invokable, but that its jump action is ;; appropriate only in certain contexts. This is the case, for ;; instance, for an Icicles search-hits bookmark. You cannot invoke ;; it outside the context of Icicles searching. For this reason, ;; these bookmarks are also shown with face
bmkp-no-jump' in the
;; bookmark-list display.
;;(@* "Editing Bookmarks")
;; ** Editing Bookmarks **
;;
;; In vanilla Emacs, you can edit the annotation associated with a
;; bookmark. And you can rename a bookmark. But that is all. There
;; is no easy way to really edit a bookmark.
;;
;; With Bookmark+:
;;
;; * You can use r' in the bookmark-list display (or
C-x x r'
;; elsewhere) to edit the name and the target file name (bookmarked
;; location) of a bookmark. You are prompted for the new names.
;;
;; * You can use e' in the bookmark-list display (or
C-x x E'
;; elsewhere) to edit a complete bookmark - all of its information.
;; You edit the internal Lisp sexp that represents the bookmark
;; record. This is the same internal definition that you see when
;; you use C-u C-h RET' in the bookmark list. ;; ;; * You can use
E' in the bookmark-list display to edit the
;; bookmark records of all of the marked bookmarks. Again, this
;; means editing their internal Lisp sexps. In particular, this
;; gives you an easy way to edit tags across multiple bookmarks.
;; All of the editing power of Emacs is available.
;;
;; * You can use T e' in the bookmark list (or
C-x x t e'
;; elsewhere), to edit a bookmark's tags.
;;
;; For all but the first of these, you are placed in a separate
;; editing buffer. Use C-c C-c' when you are done editing, to save ;; your changes. (To cancel, just kill the buffer:
C-x k'.)
;;
;; You can also clone (duplicate) a bookmark, using M-n', and then ;; edit any parts of it (e.g. using
e'). By default, the clone has
;; the same name, but with "<2>" appended. With a prefix arg you are
;; prompted for the name. Outside of the bookmark list you can use
;; C-x x 2' to clone a bookmark. ;; ;; There are many more keys and commands for editing bookmark tags. ;; You can copy tags (
C-x x t c') from one bookmark and paste them
;; to others, either replacing the original tags (C-x x t C-y') or ;; adding to them (
C-x x t q'). You can be prompted for some tags
;; to add (T +') or remove (
T -') from a bookmark. You can delete
;; a tag from all bookmarks (T d'). You can rename a tag everywhere ;; (
T r'). And you can set a tag's value.
;;
;; As usual, all such commands are also available on the Bookmark+
;; menus. The menus provide quick reminders of the available keys,
;; as does the help from ?' in the bookmark-list display. ;; ;; ;;(@* "Bookmark Records: What A Bookmark Looks Like") ;; *** Bookmark Records: What A Bookmark Looks Like *** ;; ;; It's worth dispelling some of the mystery about what a bookmark is ;; by mentioning what it looks like. This can help when you edit a ;; bookmark record. The first thing to mention is that the basic ;; structure of a bookmark record is described in the doc string of ;; variable
bookmark-alist' - but I'll repeat some of that info
;; here.
;;
;; A bookmark record is nothing more than a list whose first element
;; is a string, the bookmark name. The other list elements are
;; properties: key+value pairs that define the bookmark data. Each
;; such pair is a cons: a nonempty list or a dotted list.
;;
;; The car of the property is its name (a Lisp symbol). The cdr is
;; its value. What the value can be depends on the property - in
;; general it can be any Lisp value (number, string, list, symbol,
;; etc.). A property with a null cdr means the same thing as having
;; no such property present. For example, having the empty property
;; (tags)' is the same as having no
tags' property at all.
;;
;; There is nothing more to it: properties can be anything you like,
;; provided you provide some code to recognize them and do something
;; with them.
;;
;; Of course, the types of properties you use most (maybe always) are
;; predefined, and the vanilla bookmark.el' code and the Bookmark+ ;; code recognize and use them. The most important and most typical ;; property is this:
(filename . "/some/file/name.txt")', that is, a
;; cons whose car is the symbol filename' and whose cdr is the name ;; (a string) of the bookmarked file. ;; ;; With that in mind, you can see that renaming a bookmark just means ;; changing the string that is its car. And relocating a bookmark ;; just means changing the string that is its
filename' - e.g., from
;; (filename . "/home/foo.el")' to
(filename . "/some/other.xml")'.
;;
;; If you already have a bookmark file, typically ~/.emacs.bmk', ;; take a look at the bookmark records in it. A typical bookmark ;; also has these properties, in addition to
filename': position', ;;
front-context-string', and rear-context-string'. You can guess ;; what they are - if not, see the doc string of
bookmark-alist'.
;;
;; A Bookmark+ bookmark typically has some additional properties that
;; you can also guess. Properties time' and
visits' are updated
;; automatically each time you access the bookmark.
;;
;; Some bookmarks have a handler' property whose value is a function ;; that "jumps" to the bookmark "location". I put those two terms in ;; quotes here because a handler is really just any function - it can ;; do anything you like, and there need not be any associated ;; location. ;; ;; Some Bookmark+ bookmarks, including autofile bookmarks, just ;; "jump" to a file. The position in the file is unimportant, and ;; "jumping" does not necessarily mean visiting the file with Emacs. ;; In effect, such bookmarks are just wrappers around the file, ;; letting you get the advantage of Bookmark+ features (tags etc.) ;; for a file. Such bookmarks, which you can create using
C-x x c
;; a' or C-x x c f', contain a
file-handler' property instead of a
;; handler' property. The difference between the two is that the ;;
file-handler' value is a function (Lisp function or shell
;; command) to be applied to the file, not to the bookmark.
;;
;; Remember: A bookmark is just a persistent bit of information,
;; typically meta-information about a file and a position in that
;; file.
;;
;; I'm mentioning all of this to make the point that you cannot
;; really hurt anything if you edit a bookmark record and you mess
;; things up. The worst you can do is mess up all of your bookmarks
;; by making the file unreadable as Lisp data. (It's always a good
;; idea to back up your bookmark file from time to time.)
;;
;; And if each bookmark record after you edit it is a cons with a
;; string car then your bookmarks are generally OK, even if you might
;; have ruined the details of one or two of them. Suppose you
;; somehow mistakenly delete the a' in a
filename' property, for
;; instance. No big deal - that bookmark no longer has a
;; recognizable target location, but the other bookmarks are still
;; OK.
;;
;; The most important property for Bookmark+ users (aside from
;; filename') is probably
tags'. Its value (the cdr) is a list of
;; strings or conses - the bookmark's tags. When you create a tag,
;; it is typically a string (just its name) - e.g. "blue". If you
;; then give it a value as well, it becomes a cons with that string
;; (the name) as car and the value as cdr - e.g. ("blue" . 42)' or ;;
("blue" moonbeam 42)' - here the cdr is the list (moonbeam 42)'. ;; Here is an example of a
tags' property: (tags "hegel" ("blue" ;; . honeypot) "darwin")'. Most of the time you will use strings as ;; tags. See also (@> "Bookmark Tags Can Have Values"). ;; ;; When you edit bookmark records, just try to stay away from ;; changing any properties that you are not familiar with. And make ;; sure that when you're done you have a proper Lisp list (open ;; parens closed etc.). If you've never played with Lisp before, do ;; not panic. ;; ;; Be aware if you see dots (
.') that they are important, and they
;; must be surrounded by whitespace: . '. The amount of whitespace ;; never matters in Lisp (except inside a string etc.). ;; ;; Such a dot just separates the car of a cons from its cdr. (What's ;; a cons? Just a car with a cdr!) If the cdr is a list then we ;; typically drop the dot and the list's parens: We write
(b)'
;; instead of (b . ())' and
(a b)' instead of (a . (b))' or
(a
;; . (b . ()))'.
;;
;; Finally, remember that when you set an existing bookmark again,
;; e.g., you use C-x r m' and provide the name of an existing ;; bookmark, the existing properties are generally lost. Some are ;; automatically updated. Any that you might have added by editing ;; are lost, and any that are provided by default by the bookmark ;; handler are replaced. The only exceptions to this are the ;; properties listed in option
bmkp-properties-to-keep', which by
;; default means properties tags' and
annotation'. Any existing
;; tags and annotation are preserved when you update a bookmark.
;;(@* "Bookmark-List Views - Saving and Restoring State")
;; ** Bookmark-List Views - Saving and Restoring State **
;;
;; The bookmark list (buffer *Bookmark List*') provides a view into ;; the set of bookmarks. You can mark, sort, and hide (filter, omit) ;; bookmarks - see (@> "The Bookmark List Display"). The state of ;; the displayed bookmark list can thus change. ;; ;; At different times, and in different contexts, different views can ;; be useful. Bookmark+ lets you save the current state of the ;; displayed list and later restore it. There are a couple of ;; different ways to do this. ;; ;; ;;(@* "Quitting Saves the Bookmark-List State") ;; *** Quitting Saves the Bookmark-List State *** ;; ;; If option
bmkp-bmenu-state-file' is non-nil', which it is by ;; default, then Bookmark+ remembers the last state of the bookmark ;; list when you quit it or you quit Emacs, and it restores that ;; state when you show the list again (which could be in the next ;; Emacs session). You can think of this feature as your "Home" page ;; for bookmarks, giving you a stepping stone to the files and ;; directories you use most. ;; ;; If, for example, when you quit the bookmark list you are showing ;; only bookmarks to Info nodes and UNIX manual pages, sorted in a ;; particular way, and with some of them marked with
>' for
;; particular processing, then the next time you open the list the
;; same state is restored: the same set of bookmarks is shown, in the
;; same order, with the same markings. Deletion flags (D') and ;; modification indicators (
*') are purposefully not saved as part
;; of the display state - they are lost when you quit the display.
;;
;; You can turn off this automatic bookmark-list display state
;; saving, if you want, by customizing option bmkp-bmenu-state-file' ;; to
nil'. And you can toggle this option at any time, using
;; C-M-~' in the bookmark list (command ;;
bmkp-toggle-saving-menu-list-state'). In particular, if you want
;; your next visit to the bookmark list to start out with a
;; previously recorded state instead of the current state, just hit
;; C-M-~' before quitting the bookmark list. ;; ;; ;;(@* "State-Restoring Commands and Bookmarks") ;; *** State-Restoring Commands and Bookmarks *** ;; ;; In addition to automatically saving/restoring the final ;; bookmark-list display state, you can save this state at any time, ;; any number of times, for later restoration. This gives you the ;; ability to create multiple persistent views of your bookmarks. ;; ;; There are two ways to do this: ;; ;; * Create a bookmark for the
Bookmark List' buffer itself: a
;; bookmark-list bookmark.
;;
;; * Define a command that restores the bookmark-list state.
;;
;; When you use C-x r m' (
bmkp-bookmark-set-confirm-overwrite') in
;; buffer *Bookmark List*' to create a bookmark-list bookmark, the ;; current sort order, filter, regexp pattern, title, and omit list ;; are saved as part of the bookmark. (These concepts are described ;; below - see (@> "Bookmark List Display").) Jumping to such a ;; bookmark restores all of these. ;; ;; Alternatively, you can define a command that does the same thing, ;; but without creating another bookmark - use
C-c C-c'
;; (bmkp-bmenu-define-command') in the bookmark list to do this. ;; You are prompted for the name of the new command. Use the command ;; anytime (including in another Emacs session) to restore the ;; bookmark list. ;; ;; Define any number of such commands for the views you use. The ;; file for saving the definitions (see option ;;
bmkp-bmenu-commands-file') is never overwritten, so you can also
;; add other code to it manually, if you want. The file is read the
;; first time the bookmark list is displayed in a given Emacs
;; session.
;;
;; The state that is saved and restored using a bookmark-list
;; bookmark or a command defined using C-c C-c' is only a partial ;; state. The current set of markings and some other information are ;; not saved, in order to save disk space and save/restore time. ;; ;; Sometimes, however, you really want to save the entire ;; bookmark-list state, creating a full snapshot. You can use
C-c
;; C-C' (aka C-c C-S-c',
bmkp-bmenu-define-full-snapshot-command')
;; to do that. This defines a command that restores the bookmark
;; list completely. That is the same thing that happens
;; automatically (by default) whenever you quit the bookmark list (or
;; Emacs), but defining snapshot commands lets you have multiple
;; saved states and switch to them at will.
;;
;; Be aware, however, that full-snapshot command definitions can be
;; quite large, since they each contain a copy of the current
;; bookmark list and any accessory lists (hidden and marked bookmarks
;; etc.).
;;
;; Whether you use C-c C-c' or
C-c C-C' to define a state-restoring
;; command or you create a bookmark-list bookmark, you can create a
;; sequence bookmark that combines such bookmark-list restoration
;; with activation of other bookmarks. (To include a state-restoring
;; command in a sequence, you need to first create a function
;; bookmark that uses the command, and then include that bookmark in
;; the sequence.)
;;(@* "Bookmarking without Visiting the Target")
;; ** Bookmarking without Visiting the Target **
;;
;; There are several use cases for bookmarking a target without
;; visiting it:
;;
;; 1. In an Emacs buffer you come across a reference or a link to a
;; file or a URL. You bookmark the target without bothering to
;; visit it first. You do not really care which position in the
;; file is bookmarked.
;;
;; 2. In Dired, you mark certain files and then bookmark all (each)
;; of them, in one operation.
;;
;; 3. In a compilation buffer (e.g. *grep*',
compile') or an
;; occur or multi-occur buffer (*Occur*'), you bookmark one or ;; more of the hits. Such a bookmark takes you to the appropriate ;; position in the target file or buffer. ;; ;; 4. You bookmark a file that you might not even be able to visit in ;; Emacs (in the sense of editing it in a buffer) - for example, a ;; music file. "Jumping" to the bookmark performs an operation ;; appropriate to the file - for example, playing music. ;; ;; ;;(@* "Bookmarking a File or a URL") ;; *** Bookmarking a File or a URL *** ;; ;; You can use commands
bmkp-file-target-set' and
;; bmkp-url-target-set', bound by default to
C-x x c f' and C-x x ;; c u', to bookmark any file or URL. Completion is available, the ;; default file name or URL being determined by the text at point. ;; In addition to the file or URL, you are prompted for the bookmark ;; name. (In general, the keys
f' and u' are used in key sequences ;; for file and URL bookmarks, respectively.) ;; ;; ;;(@* "Bookmarking the Marked Files in Dired") ;; *** Bookmarking the Marked Files in Dired *** ;; ;; If you use
Dired+' (library dired+.el'), then you can bookmark ;; all of the marked files (and subdirectories) in a Dired buffer at ;; once, as autofiles, even if you normally do not or cannot visit ;; those files in Emacs. These keys are available in Dired: ;; ;;
M-b' - Bookmark each marked file
;; C-M-S-b' (aka
C-M-B') - Bookmark each marked file in a
;; bookmark-file that you specify
;; C-M-b' - Bookmark each marked file in a ;; bookmark-file you specify, and create ;; a bookmark for that bookmark-file ;; ;; Each of these commands bookmarks each of the marked files and ;; subdirectories as an autofile. By default, the bookmark file used ;; for the latter two commands is in the current directory. ;; ;; If you use multiple
C-u' as a prefix arg for these commands, then
;; you can bookmark all of the files in Dired, regardless of
;; markings, as follows:
;;
;; C-u C-u' - Use all files in Dired, except directories ;;
C-u C-u C-u' - Use all files and dirs, except .' and
..'
;; C-u C-u C-u C-u' - Use all files and all directories ;; ;;
C-M-b' not only bookmarks each of the marked files, it also
;; creates a bookmark-file bookmark for that set of bookmarks. See
;; (@> "Bookmark-File Bookmarks"), below.
;;
;; You can later "jump" to that bookmark to load its set of
;; bookmarks. If you use C-u' when you jump to it, then you switch ;; bookmark files, so that
C-x x e' (or C-x r l') displays only the ;; bookmarks created from the marked files. Without
C-u', jumping
;; to the bookmark-file bookmark simply loads its bookmarks into the
;; current set of bookmarks.
;;
;;
;;(@* "Bookmarking Compilation, Grep, and Occur Hits")
;; *** Bookmarking Compilation, Grep, and Occur Hits ***
;;
;; In a similar way, you can bookmark the file or buffer positions of
;; selected hits in a compilation buffer (including *grep*') or an ;;
occur' or multi-occur' buffer. ;; ;;
C-c C-b' in such a buffer bookmarks the target of the hit at
;; point. C-c C-M-b' bookmarks the target of each hit in the ;; buffer. ;; ;;
C-c C-M-b' in these buffers is thus similar to M-b' in a Dired ;; buffer. Unlike Dired, however, there is no way to mark such hits. ;; Every hit is bookmarked. ;; ;; Nevertheless, you can get the same effect. Just use
C-x C-q' to
;; make the buffer writable (e.g. temporarily), and then remove any
;; hits that you do not want to bookmark. You can remove hits anyway
;; you like, including by C-k' and by regexp (
M-x flush-lines' or
;; M-x keep-lines'). ;; ;; See also: (@> "Autonamed Bookmarks - Easy Come Easy Go"), ;; bookmarking occur hits using autonamed bookmarks. ;; ;; ;;(@* "Bookmarking Files That You Cannot Visit with Emacs") ;; *** Bookmarking Files That You Cannot Visit with Emacs *** ;; ;; You use lots of files that you never visit using Emacs, but that ;; you might like to keep track of or access in other ways: music ;; files, image files, whatever. ;; ;; You can define a new kind of bookmark for any file type you are ;; interested in, implementing a bookmark handler for it that ;; performs the appropriate action on it when you "jump" to it. That ;; action needs to be expressible using an Emacs function, but it ;; need not have anything to do with visiting the file in Emacs. ;; ;; When you bookmark a target file that Emacs recognizes as an image ;; or sound file, an appropriate handler is used automatically. ;; ;; After you create individual bookmarks for, say, music or image ;; files, you can use
P B' in the bookmark-list display to show only
;; those bookmarks, and then use C-x r m' to bookmark that state of ;; the bookmark-list. ;; ;; That bookmark-list bookmark in effect becomes a music playlist or ;; an image library or slideshow. Jump to it anytime you want to ;; listen to that set of music pieces or view those images. And you ;; can use
C-x x B' and then C-x x next' to cycle among the music ;; pieces or images (slideshow). (See (@> "Cycling the Navigation List").) ;; ;; Together with the use of bookmark tags, this gives you a handy way ;; to organize and access objects of any kind. See (@> "Bookmark Tags"). ;; ;; You use option
bmkp-default-handlers-for-file-types' to control
;; which operation (handler) to use for which file type. This is a
;; set of associations (an alist) with each key being a regexp
;; matching a file name, and with each associated value being a Lisp
;; sexp that evaluates to either a shell command (a string) or an
;; Emacs function (a symbol or lambda form).
;;
;; You can think of bmkp-default-handlers-for-file-types' as ;; somewhat analogous to
auto-mode-alist'. But it maps file-name
;; patterns to file actions instead of mapping them to buffer modes.
;; And it has an effect only when you use certain commands.
;;
;; The handler for the bookmark created invokes the shell command or
;; the Emacs function with the file name as argument.
;;
;; Here is an example option value:
;;
;; (("\.ps$" . "gsview32.exe")
;; ("\.html?$" . browse-url)
;; ("\.doc$" . w32-browser))
;;
;; This value causes creation of bookmarks that, when you jump to
;; them, invoke:
;;
;; * shell command gsview32.exe' on the bookmark's ;; target file if it is PostScript (extension
.ps')
;;
;; * Emacs Lisp function browse-url' on the file if it is HTML ;; (extension
.htm' or .html') ;; ;; * Emacs Lisp function
w32-browser' on the file if the file
;; extension is .doc' (e.g., a Microsoft Word file) ;; ;; The default value of
bmkp-default-handlers-for-file-types' is
;; taken from the value of option dired-guess-shell-alist-user' ;; (from Dired X). ;; ;; The associations are checked in order, and the first one that ;; matches the given file name is used. You can thus order them to ;; deal with overlapping file-name patterns. ;; ;; If no matching file association is found in ;;
bmkp-default-handlers-for-file-types', and if option
;; bmkp-guess-default-handler-for-file-flag' is non-
nil' (it is
;; nil' by default), then Bookmark+ will guess a shell command to ;; use. It does this by matching the file name against ;;
dired-guess-shell-alist-default' (also from Dired X). In Emacs
;; 23 and later, if it finds no shell command that way then it
;; guesses one based on mailcap entries.
;;
;; When a bookmark is created using C-x x c f' or
C-x x c a' for a
;; file that matches bmkp-default-handlers-for-file-types', the ;; shell command or Lisp function that "jumps to" (opens) the file is ;; saved in the bookmark as property
file-handler' (not handler'). ;; ;; ;;(@* "Opening Bookmarks Using Windows File Associations") ;; *** Opening Bookmarks Using Windows File Associations *** ;; ;; If you use Microsoft Windows there is no need to define new ;; bookmark types and handlers, if the action you want is the one ;; that Windows associates with the file. You already have a set of ;; file/program associations, and Bookmark+ recognizes these as ;; alternative handlers. ;; ;; You can thus take advantage of Windows file associations to open ;; bookmarks for files of all kinds. To do this, you also need ;; library
w32-browser.el'. In the bookmark list, the following
;; keys are bound to commands that open bookmarks using the
;; associated Windows Open' applications: ;; ;;
M-RET' - bmkp-bmenu-w32-open' ;;
M-mouse-2' - bmkp-bmenu-w32-open-with-mouse' ;;
M-o' - bmkp-bmenu-w32-jump-to-marked' ;; ;; Windows file associations are always available to you, in addition ;; to any other file associations that you define using ;;
bmkp-default-handlers-for-file-types' (see
;; (@> "Bookmarking Files That You Cannot Visit with Emacs")).
;;
;; You can thus have two different programs associated with the same
;; kind of file. Your MS Windows file association for PostScript
;; might, for example, use Adobe Distiller to create a PDF file from
;; PostScript, while your bmkp-default-handlers-for-file-types' ;; association for PostScript might use GhostView to display it ;; directly. ;; ;; Besides using
M-RET' etc. in buffer *Bookmark List*', if in ;;
bmkp-default-handlers-for-file-types' you register w32-browser' ;; as the association to use for a given file pattern, then you can ;; use command
bmkp-w32-browser-jump' (not bound, by default)
;; anywhere to open a bookmark whose file name matches that pattern,
;; using its Windows file-association program.
;;
;; You can also specify w32-browser' as the bookmark "type" when you ;; use command
bmkp-jump-to-type' (C-x j :'). Either of these ;; approaches gives you a way to use completion to choose a bookmark ;; to open using a Windows file association. ;; ;; Specifying such an association in ;;
bmkp-default-handlers-for-file-types' means that bookmarks for
;; such a file will have a file-handler' value of
w32-browser', to
;; "jump" to (i.e., open) the file.
;;
;; To set up a given file extension for use this way, add an entry
;; (REGEXP . w32-browser) to option
;; bmkp-default-handlers-for-file-types', where REGEXP matches the ;; file extension. ;; ;; For example, to make a command such as
bmkp-bookmark-a-file'
;; (C-x x c a') automatically bookmark
.doc' files using the
;; associated MS Windows program (typically MS Word), add this entry:
;; ("\.doc$" . w32-browser).
;;
;;
;;(@ "Autofile Bookmarks")
;; *** Autofile Bookmarks ***
;;
;; An autofile bookmark, or just an autofile, is a bookmark to a file
;; or directory that uses the nondirectory part of its file name (or
;; of its directory-file-name', if a directory name) as the bookmark ;; name. ;; ;; You can look at an autofile bookmark as just a wrapper around a ;; file or directory: a way to attach meta information (such as tags) ;; to it. But you can use an autofile bookmark much as you would use ;; a file or directory. ;; ;; To create a new autofile bookmark, you can use ;;
bmkp-bookmark-a-file' (aka bmkp-autofile-set'), which is bound ;; by default to
C-x x c a'. (In general, the key a' is used in ;; key sequences for autofile bookmarks.) ;; ;; If user option
bmkp-propertize-bookmark-names-flag' is non-nil', ;; which it is by default with Emacs 21 and later, then you can have ;; multiple bookmarks with the same name. This is important for ;; autofile bookmarks because the bookmark name is only the ;; nondirectory part of the file name. This Bookmark+ feature lets ;; you have different autofile bookmarks for files of the same name ;; in different directories. ;; ;; In addition to the single autofile bookmark that you can create ;; for a given absolute file location, you can of course create ;; additional bookmarks to the same file or directory, using ;; different bookmark names. Among other things, this lets you tag ;; the same file or directory in different ways. ;; ;; You can use
C-x j a' (bmkp-autofile-jump') or
C-x 4 j a'
;; (bmkp-autofile-jump-other-window') to visit an autofile bookmark. ;; And there are commands for visiting an autofile that is tagged in ;; certain ways. For example,
bmkp-autofile-some-tags-regexp-jump'
;; (C-x j t a % +') jumps to an autofile bookmark that has at least ;; one tag matching a given regexp. See (@> "Tagging Files"). ;; ;; You can create autofiles automatically whenever you use an Emacs ;; file-cache command, by customizing user option ;;
bmkp-autofile-filecache'. See the Emacs manual, node File Name ;; Cache'. ;; ;; This optional bookmark creation can replace adding the file to the ;; cache, or it can be in addition to caching the file. This is done ;; by advising command
file-cache-add-file', which means that it
;; affects also the other Emacs file-cache commands that use that
;; function, directly or indirectly:
;;
;; * file-cache-add-directory' ;; *
file-cache-add-directory-list'
;; * file-cache-add-directory-recursively' ;; *
file-cache-add-directory-using-find'
;; * file-cache-add-directory-using-locate' ;; *
file-cache-add-file-list'
;;
;; See the Emacs manual, node File Name Cache'. ;; ;; If option
bmkp-autofile-access-invokes-bookmark-flag' is
;; non-nil' then regular access of a file or directory ;; (e.g.
find-file') invokes the associated autofile bookmark, if
;; there is one. This has the effect of updating the bookmark data,
;; such as the number of visits. The default value of the option is
;; nil'. To set the option value, either use Customize ;; interactively or use a Customize function. ;; ;; Finally, if you use libraries
Dired+' and highlight.el' then ;; autofiles are highlighted specially in Dired, and the highlighting ;; indicates whether the file is tagged. ;; ;; ;;(@* "A Type-Aware
find-file'")
;; *** A Type-Aware find-file' *** ;; ;; User option
bmkp-default-handlers-for-file-types' (see
;; (@> "Bookmarking Files That You Cannot Visit with Emacs")) gives
;; you a way to associate a file type, as determined by the file
;; name (typically its extension) with a default file action. This
;; is like MS Windows file associations, but it is specific to Emacs
;; and Bookmark+. And it is useful for more than just bookmarks.
;;
;; Commands bmkp-find-file' (
C-x j C-f') and
;; bmkp-find-file-other-window' (
C-x 4 j C-f') take advantage of
;; this association to open files. If a file name matches no pattern
;; in bmkp-default-handlers-for-file-types' then these commands act ;; like
find-file' and find-file-other-window'. Otherwise, the ;; invoke the associated file handler in ;;
bmkp-default-handlers-for-file-types'.
;;
;; Invoking the handler is just what the ordinary autofile jump
;; commands (e.g. C-x j a') do. But
bmkp-find-file' is different
;; in a couple of ways.
;;
;; Like vanilla find-file' (
C-x C-f'), C-x j C-f' and
C-x 4 j
;; C-f' use read-file-name' to prompt you for the file name. The ;; completion candidates are the names of all of the files in the ;; current directory (
default-directory'), that is, the directory of
;; your current minibuffer input. This includes the names of any
;; autofile bookmarks in the same directory. And like C-x C-f' you ;; can change directory, navigating up and down the file hierarchy. ;; In sum, these commands are file-aware. ;; ;; The ordinary autofile jump commands on the other hand use ;;
completing-read' to complete your input against all autofile
;; bookmark names, regardless of directory. And since the bookmark
;; names reflect only the relative file names, it is not so easy to
;; distinguish two autofiles with the same name but in different
;; directories. (Icicles' can help here, BTW.) ;; ;; There is a
bmkp-find-file-' command that corresponds to each
;; bmkp-autofile-' command. For example, ;;
bmkp-find-file-some-tags-regexp' (C-x j t C-f % +') corresponds ;; to
bmkp-autofile-some-tags-regexp-jump' (C-x j t a % +'). All ;;
bmkp-find-file' commands use C-f' in their key bindings, as a ;; reminder of their reading file names a la
find-file'.
;;
;; But whereas C-x j C-f' and
C-x 4 j C-f' let you access any file,
;; the other bmkp-find-file-' commands, which find files that have ;; certain tags, provide only autofiles as completion candidates. ;; That's obvious, since files are tagged by bookmarking them. ;; ;; You can thus use the
C-f' commands to take advantage of
;; file-action associations that you define. But if you want to
;; associate metadata (e.g. tags) with files or directories, then you
;; will want to create autofiles. You can do this when you invoke
;; these commands, by providing a prefix argument. Thus, for
;; example, C-u C-x j C-f foo.doc' opens file
foo.doc', respecting
;; any handler recorded for it via option
;; bmkp-default-handlers-for-file-types' - but it also creates an ;; autofile bookmark for it. ;; ;; Whenever an autofile bookmark is used, regardless of whether you ;; access it using a
bmkp-autofile*' command or a bmkp-find-file*' ;; command, the full bookmark record (including handler) is taken ;; into account. ;; ;; Note, however, that the
C-f' tag commands differ from the a' tag ;; commands in how the completion candidates are filtered. ;; ;; For the former,
read-file-name' is passed a predicate that is
;; applied to each file name in the directory, filtering out any such
;; candidates that do not satisfy it (e.g., do not have the required
;; tags).
;;
;; This happens before you type any input to match the file name.
;; The predicate checks for a corresponding autofile and checks its
;; tags (depending on the command). If there are lots of files in
;; the current directory, this can take a while.
;;
;; For the latter, similar tests are made, but instead of testing
;; each file in the current directory, these commands test each
;; bookmark in the current bookmark list. If there are lots of
;; bookmarks this can take a while.
;;
;; In some cases a C-f' command is quicker; in some cases a
a'
;; command is quicker.
;;
;; If you use Icicles', then the performance hit for
C-f' when
;; there are lots of files in a directory is greatly reduced. This
;; is because Icicles' applies the filtering predicate after, not ;; before, you type text in the minibuffer. In other words, instead ;; of testing each file in the directory, it tests only the files ;; that match your input. (In addition, if you use
Icicles' then
;; you get multi-command versions of each of these bookmark commands,
;; which means that you can visit more than one file per command
;; invocation.)
;;(@* "Tagging Files")
;; ** Tagging Files **
;;
;; Section (@> "Tags: Sets of Bookmarks") covers bookmark tags, which
;; are persistent metadata that you define to help you organize
;; bookmarks into meaningful sets.
;;
;; Section (@> "Autofile Bookmarks") describes autofile bookmarks,
;; which, in effect, let you treat files and directories generally as
;; if they were bookmarks. You can choose a file or directory to
;; visit or act on by its name and location, but also by its bookmark
;; metadata.
;;
;; In particular, you can tag a file or directory - that is, specify
;; tags for its associated autofile bookmark. And you can then visit
;; a file or directory that has a given set of tags. Bookmark+
;; provides commands that automatically create and manipulate
;; autofile bookmarks, that is, bookmarks that have the same name as
;; the files or directories they tag.
;;
;; Command bmkp-tag-a-file' (aka
bmkp-autofile-add-tags'), bound by
;; default to C-x x t + a', prompts you for a set of tags and a file ;; or directory, and creates or sets the corresponding autofile ;; bookmark. Command
bmkp-untag-a-file' (aka
;; bmkp-autofile-remove-tags'), bound by default to
C-x x t - a',
;; similarly lets you remove specified tags from a file or directory.
;;
;; If you also use library Icicles', then you can act on multiple ;; files and directories during the same command (a "multi-command"). ;; You can thus all at once tag a set of files and directories the ;; same way, or act on a set of files and directories that are tagged ;; similarly.
Icicles' also lets you create autofiles or add or
;; remove tags, on the fly, whenever you use commands (e.g. C-x ;; C-f') that access files or directories. ;; ;; If you also use library
Dired+' (dired+.el') then you can use ;;
C-+' to add tags to the marked files and directories, and C--' ;; to remove tags from them. You can use
C-M-+' and C-M--' to do ;; the same thing for the current file. You can also use items from ;; the Dired menus to do these things. ;; ;; Bookmark+ provides two kinds of command for visiting files ;; associated with bookmarks that have tags. ;; ;; The first kind uses bookmarks directly: you choose a bookmark ;; name, not a file name, but the candidates are only file and ;; directory bookmarks. These commands have the prefix
bmkp-file-'
;; or bmkp-autofile-'. ;; ;; As a special case, commands with the prefix
bmkp-file-this-dir-'
;; limit the choices to bookmarks for files and subdirectories of the
;; current directory. By default, the commands across all
;; directories are on prefix key C-x j t f', and those for the ;; current directory only are on prefix key
C-x j t .'. See
;; (@> "Different Types of Jump Commands") for more about these
;; commands.
;;
;; The second kind of command is for visiting tagged files, that is,
;; autofile bookmarks, just like the commands with prefix
;; bmkp-autofile-'. However, these commands do not handle the ;; bookmark as such, but only its associated file or directory. They ;; recognize its tags, but they pay no attention to any special ;; handler or other recorded information. ;; ;; These commands have the prefix
bmkp-find-file-', and they are on
;; the prefix key C-x j t C-f'. The
C-f' here is intended to
;; remind you of command find-file' (
C-x C-f'). Like find-file', ;; they use
read-file-name' to read the bookmark's file name,
;; instead of using completing-read' to read the bookmark name. ;; ;; Yes, for an autofile bookmark the bookmark name and the relative ;; file name are the same. But
read-file-name' is file-aware, and
;; lets you browse up and down the directory hierarchy.
;;
;; The bmkp-find-file-' commands are available only for Emacs 22 and ;; later (because they use
read-file-name' with a PREDICATE
;; argument).
;;
;; For example:
;;
;; C-x j t f % +' is
bmkp-file-some-tags-regexp-jump'
;; C-x j t . % +' is
bmkp-file-this-dir-some-tags-regexp-jump'
;; C-x j t a % +' is
bmkp-autofile-some-tags-regexp-jump'
;; C-x j t C-f % +' is
bmkp-find-file-some-tags-regexp'
;;
;; * The first of these visits any file or directory bookmark that
;; has at least one tag among the tags you specify, and you choose
;; among bookmark names. The file or directory can be anywhere.
;;
;; * The second is similar to the first, but only bookmarks for files
;; in the current directory are completion candidates.
;;
;; * The third is similar to the first, but only autofile bookmarks
;; are completion candidates.
;;
;; * The fourth is similar to the third regarding tags, but it uses
;; read-file-name', so you can browse up and down the file ;; hierarchy. The completion candidates are file and directory ;; names, not bookmark names. ;; ;; If you use
Icicles', there are similar sets of commands, but they
;; all let you act on multiple files and directories at the same time
;; (multi-commands). For example, you can delete (or byte-compile
;; or...) a set of files and directories according to their tags.
;;
;; Remember that you can create multiple bookmarks for the same file
;; or directory, providing them with different sets of tags. (Only
;; one of the bookmarks is the autofile bookmark.)
;;
;; You can also use multiple bookmark files (the files that record
;; bookmarks). Different projects can thus have different tags for
;; the same sets of files and directories, even using just autofile
;; bookmarks. See (@> "Using Multiple Bookmark Files").
;;
;; A file or directory bookmark can have any number of tags, and
;; multiple such bookmarks can have the same tag. You can sort,
;; show/hide, or mark files and directories based on their tags.
;;(@* "Using Multiple Bookmark Files")
;; ** Using Multiple Bookmark Files **
;;
;; Bookmark-list views (see
;; (@> "Bookmark-List Views - Saving and Restoring State")) provide
;; one way to switch among various sets of bookmarks that you use.
;; But that feature affects only the bookmarks that you see displayed
;; in buffer *Bookmark List*', not the actual set of available ;; bookmarks. ;; ;; The bookmarks available to you are defined in a bookmark file. By ;; default, they are stored in the file named by option ;;
bmkp-last-as-first-bookmark-file', if non-nil', otherwise in the ;; file named by option
bookmark-default-file' (~/.emacs.bmk', by ;; default). ;; ;; If you use only one bookmark file then you never need to load or ;; save it manually. Emacs does that for you automatically. ;; ;; But you can have multiple bookmark files if you want, and at any ;; time you can change the bookmark file that is current. To do ;; that, use
C-x x L' (or just L' in the bookmark-list display), ;; which is bound to command
bmkp-switch-bookmark-file-create'.
;; Having multiple bookmark files gives you an added degree of
;; flexibility.
;;
;; By default, the last bookmark file you used, in your last Emacs
;; session, is the initial bookmark file that is loaded automatically
;; in your next session. But if you prefer, you can make Bookmark+
;; always start with the same bookmark file
;; (bookmark-default-file'). User option ;;
bmkp-last-as-first-bookmark-file' controls this.
;;
;; You can easily see which bookmark file is current at any time: It
;; is shown at the top of buffer *Bookmark List*', and it is near ;; the top of the help output from command ;;
bmkp-bmenu-mode-status-help', which is what is bound to ?' and ;;
C-h m' in buffer *Bookmark List*'. ;; ;; When you switch to another bookmark file, the default choice for ;; the file to switch to is the last bookmark file you used (in the ;; same session). So it is trivial to toggle back and forth between ;; two bookmark files: just hit
RET' to accept the default.
;;
;; When bookmarks are saved automatically, or when you save them
;; using bookmark-save' (
S' in the bookmark-list display or C-x x ;; s' globally) and you don't use a prefix argument, they are saved ;; in the current bookmark file. ;; ;; You can turn off the automatic saving of the current bookmark ;; file, by customizing option
bookmark-save-flag' to nil'. And ;; you can toggle this option at any time, using
M-' in the
;; bookmark list (command ' to turn it back on again. And remember that, as long as
;; you have not saved bookmarks after loading, you can always use
;; bmkp-toggle-saving-bookmark-file'). ;; ;; Besides using multiple bookmark files as *alternatives*, you can ;; combine them, using them as component bookmark subsets (like ;; modules). To do that, use command
C-x x l' (lowercase l'), ;; which is bound to
bookmark-load', and do not use a prefix
;; argument. (Using a prefix argument with C-x x l' is the same as ;; using
C-x x L': it switches bookmark files.) Here too the
;; default is the name of the last bookmark file that you used.
;;
;; In the *Bookmark List*' display you can use
M-l' to load all of
;; the bookmark files corresponding to the marked bookmark-file
;; bookmarks, in the order in which they are displayed. Any non
;; bookmark-file bookmarks that are marked are ignored. Before
;; loading, if any of your currently loaded bookmarks have been
;; modified then you are asked if you want to save them first, before
;; loading the others.
;;
;; After loading, to avoid confusion and possible mistakes, automatic
;; saving to the current bookmark file is turned off. You can always
;; use `M-C-u g' to revert to the bookmarks saved in the bookmark file. ;; ;; To create additional bookmark files, to use either as alternatives ;; or as components, you can either copy an existing bookmark file or ;; use
bmkp-empty-file' (C-x x 0') to create a new, empty bookmark ;; file. If you use
C-x x 0' with an existing bookmark file, then
;; its bookmarks are all deleted - it is emptied.
;;
;; Instead of simply copying a bookmark file, you can use
;; bookmark-save' with a prefix argument, or use
bookmark-write'
;; (bound to C-x x w'), to save the currently defined bookmarks to a ;; different bookmark file. ;; ;; However a bookmark file was created, you can switch to it and then ;; add or delete bookmarks selectively, to change its content. ;; Remember too that you can delete bookmarks from the current set ;; using command
bookmark-delete' (C-x x d') or, in the bookmark ;; list, using
d' plus x' or marking then
D'.
;;
;; Deleting bookmarks from a bookmark file is one way of editing it.
;; Another is to copy or move bookmarks from one bookmark file to
;; another. In the bookmark-list display, you can copy or move the
;; marked bookmarks (or the current bookmark, if none are marked)
;; from the current bookmark file to another that you name, using Y ;; > +' (
bmkp-bmenu-copy-marked-to-bookmark-file') and Y > -' ;; (
bmkp-bmenu-move-marked-to-bookmark-file'), respectively. And
;; you can use Y > 0' ;; (
bmkp-bmenu-create-bookmark-file-from-marked') to create a new
;; bookmark file by copying the marked bookmarks. With a prefix arg,
;; Y > 0' creates also a bookmark-file bookmark. ;; ;; In any location (any file or any buffer that can be bookmarked), ;; you can switch to a bookmark file that has only bookmarks for the ;; current file or buffer, creating such a file on the fly if none ;; exists. To do this, use
C-x x C-l'
;; (bmkp-switch-to-bookmark-file-this-file/buffer'). ;; ;; NOTE: ;; ;; Unlike the other ways of organizing bookmarks into sets (tags, ;; bookmark-list bookmarks, etc.) bookmark files represent ;; physical, not logical, groupings of bookmarks. A bookmark file ;; contains complete bookmark records. ;; ;; If you copy a bookmark from one bookmark file to another, the ;; copy is an independent bookmark: it has no relation to the ;; bookmark it was copied from. Changes to the copy or the ;; bookmark it was copied from do not affect each other. ;; ;; This means that to use bookmark files for organizing bookmarks ;; you will typically move, not copy, bookmarks between them (or ;; copy and later delete). Remember that you can load multiple ;; bookmark files to access their bookmarks together in a session. ;; Think of your bookmark files as independent modules that you can ;; combine. ;; ;; See Also: (@> "Bookmark+ Load Order and Option
bookmark-default-file'").
;;
;;
;;(@* "Bookmark Files For Bookmarks with Specific Tags")
;; *** Bookmark Files For Bookmarks with Specific Tags ***
;;
;; Bookmark+ provides various features for creating, manipulating,
;; and making use of bookmarks, but it generally doesn't provide
;; predefined ways to use such features together to accomplish a
;; particular goal.
;;
;; This includes uses of features to organize bookmarks and their
;; destinations or results/effects. But here's an example of using a
;; couple features out of the box to do that: create a bookmark file
;; for bookmarks with a given set of tags.
;;
;; You can have multiple bookmark files, which you can use separately
;; or in combination. If you use tags as a way of "categorizing"
;; bookmarks then you might create one or more bookmark files for
;; bookmarks tagged in particular ways. For example, have a bookmark
;; file that contains only bookmarks tagged both travel' and
2024'.
;;
;; Loading that file alone gives you access to just those bookmarks,
;; simplifying bookmark commands (jump, tag, filter, edit,...).
;; Loading it together with another bookmark file, for example one
;; for bookmarks with another set of tags, gives you access to both
;; sets.
;;
;; Here's one way to create a bookmark file for bookmarks tagged in a
;; particular way, using the bookmark-list display for a set of
;; bookmarks that includes those bookmarks but also others: mark the
;; bookmarks you want, then create a bookmark file from the marked
;; bookmarks.
;;
;; 1. Unmark all bookmarks, using U'. ;; ;; 2. Mark the bookmarks that have the tags you're interested in. ;; ;; You can do this using tags-command keys that mark according to ;; their tags. These keys all begin with prefix key
T m'. For
;; example, to mark bookmarks that are tagged with both travel' ;; and
2024' you can use T m *' and enter
travel' and 2024' ;; when prompted (end with an empty
RET').
;;
;; Or if you want bookmarks with either travel' or
2024' (or
;; both), use T m +'. Another way to do this is to use
T m %'
;; and enter the regexp \(travel\|2024\)'. ;; ;; (Marking and unmarking commands are also in menu
Bookmark+' >
;; Mark'.) ;; ;; 3. Copy the marked bookmarks to a new bookmark file. ;; ;; Use
Y > 0' to do this, entering the file name at the prompt.
;;
;; Or if you want to move the bookmarks instead of copying them
;; (i.e., remove them from the current bookmark file), use Y > ;; -'. ;; ;; (Bookmark-file commands are also in menu
Bookmark+' >
;; Bookmark File'.) ;; ;; See Also: (@> "Tag Commands and Keys"). ;; ;; ;;(@* "Bookmark-File Bookmarks") ;; *** Bookmark-File Bookmarks *** ;; ;; A bookmark file is an excellent, persistent way to represent a set ;; of bookmarks. In particular, it can represent a project or a ;; project component. Switch among bookmark files to access ;; different projects. Load project components as you need them. ;; ;; You can load a bookmark file using
C-x x L' (switch) or C-x x l' ;; (accumulate). As a convenience, you can also load a bookmark file ;; by jumping to a bookmark-file bookmark. ;; ;; You use command
bmkp-set-bookmark-file-bookmark', bound to C-x x ;; y', to create a bookmark-file bookmark. Jumping to such a ;; bookmark just loads the bookmark file that it records. With
C-u'
;; (e.g. C-u C-x j y project-foo'), jumping switches bookmark files. ;; Without
C-u' it accumulates the loaded bookmarks.
;;
;; You can also use commands bmkp-bookmark-file-load-jump' and ;;
bmkp-bookmark-file-switch-jump' (unbound by default), which load
;; and switch without prompting you for confirmation or whether to
;; first save the current bookmark file.
;;
;; A bookmark-file bookmark is not only an added convenience. You
;; can also use it in combination with other Bookmark+ features, such
;; as tagging.
;;
;; As a shortcut, in Dired (if you use library Dired+'),
C-M-b'
;; creates a bookmark-file bookmark. The bookmark file that it
;; records contains autofile bookmarks to each of the files and
;; subdirectories that was marked in Dired at the time it was
;; created. Jumping to that bookmark-file bookmark makes those
;; (marked) files and subdirectories available as bookmarks. See
;; also (@> "Use Dired to Bookmark Files without Visiting Them").
;;
;; Note that the bookmark file in which a bookmark-file bookmark is
;; recorded is not the same as the bookmark file recorded in that
;; bookmark.
;;
;; For example, when you use C-M-b' in Dired, the bookmark-file for ;; the marked files is, by default, file
.emacs.bmk' in the Dired
;; directory. So if you are in directory /foo/bar' the default ;; bookmark file for the marked files is
/foo/bar/.emacs.bmk'. But
;; the new bookmark-file bookmark created is recorded in the current
;; bookmark file, whatever that might be (e.g. `~/.emacs.bmk').
;;(@* "The Bookmark List Display")
;; ** The Bookmark List Display **
;;
;; Bookmark+ enhances the bookmark list (aka the bookmark "menu
;; list", a misnomer) that is displayed in buffer *Bookmark List*' ;; when you use
C-x x e' or C-x r l' (command ;;
bookmark-bmenu-list').
;;
;; At the top of the bookmark-list display is this header
;; information:
;;
;; * The bookmark file used currently. This is important because
;; Bookmark+ makes it easy for you to have multiple bookmark files
;; and switch among them.
;;
;; * A title that describes the kinds of bookmarks listed, that is,
;; it reflects athe current filtering, if any.
;;
;; For example, this header indicates that the current bookmark file
;; is c:/.emacs.bmk' and only file and directory bookmarks are ;; shown: ;; ;; Bookmark file: ;; c:/.emacs.bmk ;; ;; File and Directory Bookmarks ;; ---------------------------- ;; ;; (Bookmark+ does not use the sliding header line of vanilla Emacs ;; 24-27, which means that option
bookmark-bmenu-use-header-line'
;; has no effect. You do not need to see Bookmark' and
File'
;; column headers as you scroll. Bookmark+ also does not use
;; tabulated-list-mode, as vanilla Emacs 28+ does. That mode is too
;; limited.)
;;
;; Bookmarks are highlighted to indicate their type. You can mark and
;; unmark bookmarks, show or hide bookmarks of particular types, and
;; more. Bookmarks that have tags are marked with a t'. Bookmarks ;; that have an annotation are marked with an
a' (not with a *' as ;; in vanilla
bookmark.el'). Bookmarks that have been modified
;; since the last save of the bookmark file are marked with a *'. ;; Bookmarks that have bookmark-highlight override settings (see ;; (@> "Defining How to Highlight")) are marked with a one-character ;; pink background. ;; ;; Use
?' or C-h m' in buffer
Bookmark List' for more
;; information about the bookmark list, including the following:
;;
;; * The current status of sorting, filtering, and marking.
;;
;; * A legend for the faces used for different bookmark types.
;;
;;
;;(@* "Jumping To Bookmarks from the Bookmark List Display")
;; *** Jumping To Bookmarks from the Bookmark List Display ***
;;
;; Bookmark visiting (jumping) commands are globally on prefix keys
;; C-x j' and
C-x 4 j'. In the bookmark-list display they are
;; additionally on j' (other window) and
J' (same window). In
;; addition, j >' is bound to
bmkp-bmenu-jump-to-marked', which
;; jumps to each of the marked bookmarks in other windows.
;;
;;
;;(@* "Tag Commands and Keys")
;; *** Tag Commands and Keys ***
;;
;; There are lots of tag-related bookmark commands, and most are
;; bound to keys in buffer *Bookmark List*' as well as to other keys ;; outside it. How can you keep the commands straight or remember ;; their keys? ;; ;; In the bookmark list display, tags-command keys begin with prefix ;; key
T'. Elsewhere, they begin with prefix key C-x x t' (or
C-x
;; j t', for jump commands - see (@> "Different Types of Jump Commands")).
;;
;; C-h m' (or
?') is your friend, of course. Likewise T C-h', ;;
C-x x t C-h', and C-h >' (which describes the marked bookmarks). ;; Beyond that, the tag-related keys that are more than two ;; keystrokes are organized as follows: ;; ;; They all have the prefix key
T'.
;;
;; m' means mark ;;
u' means unmark
;; >' stands for the marked bookmarks ;;
' means AND (set intersection; all)
;; +' means OR (set union; some/any) ;;
' means NOT (set complement)
;;
;; The key ')
;; have any (T m *', for instance, marks (
m') the bookmarks that are
;; tagged with all (*' = AND) of a given set of tags. It prompts you ;; for one or more tags that the bookmarks must have, and it marks ;; all bookmarks that have all of the tags you enter. ;; ;; The key
T u ~ +' unmarks (u') the bookmarks that do not (
+' = OR) of the tags you specify. And so on. ;; ;; The marking and unmarking commands for tags compare the tags a ;; bookmark has with tags that you enter. Any bookmarks that have no ;; tags are ignored - they are neither marked nor unmarked by these ;; commands. ;; ;;
+' and -' can also mean add and remove tags, respectively, and ;;
>' stands for the marked bookmarks. So T > +' adds (
+') one or
;; more tags to each of the marked (>') bookmarks. ;; ;; In general, the tag-related commands let you enter a set of tags, ;; one at a time. Thus, instead of having a command that adds a ;; single tag to the current bookmark, you have a command that adds ;; any number of tags to it. To add just a single tag, hit
RET'
;; twice: once to enter the tag, and once again to indicate that it
;; is the last (i.e., the only) one.
;;
;; If you just hit RET' immediately, specifying an empty set of ;; tags, then each of the commands does something appropriate. For ;;
T m ', for instance, an empty list of tags means to mark (only)
;; the bookmarks that have any tags at all.
;;
;; Finally, for the marking/unmarking tags commands, a prefix
;; argument flips the sense of the command, in this way:
;;
;; "some are" -> "some are NOT", i.e., "not all are" (and vice versa)
;; "all are" -> "all are NOT", i.e., "none are" (and vice versa)
;;
;; In other words:
;;
;; C-u T m * = T m ~ + (all are NOT = not some are)
;; C-u T m ~ + = T m * (not some are NOT = all are)
;; C-u T m + = T m ~ * (some are NOT = not all are)
;; C-u T m ~ * = T m + (not all are NOT = some are)
;;
;; You'll figure it out ;-).
;;
;; Other important keys pertaining to tags (the keys in parentheses
;; work in any buffer, not just buffer *Bookmark List*'): ;; ;; *
C-h RET' (C-h M') shows you the tags that belong to a ;; bookmark. With a prefix argument it shows you the full internal ;; form of the tags, that is, the name+value pairs. ;; ;; *
C-h >' describes all of the marked bookmarks, in the current
;; sort order. The descriptions include the tags. (You can use T ;; m * RET' to mark all of the tagged bookmarks.) ;; ;; *
T e' (C-x x t e') lets you edit a bookmark's tags. ;; ;; *
T l' (C-x x t l') lists all tags currently known to Emacs ;; (across all bookmarks). ;; ;; *
T +' (C-x x t + b') adds some tags to a bookmark. ;;
T -' (C-x x t - b') removes some tags from a bookmark. ;;
T 0' (C-x x t 0) removes all tags from a bookmark. ;;
T d' (C-x x t d) removes a set of tags from all bookmarks. ;; ;; In the bookmark list display you can also sort bookmarks according ;; to how they are tagged, even in complex ways. See ;; (@> "Sorting Bookmarks"). ;; ;; ;;(@* "Tags: Sets of Bookmarks") ;; *** Tags: Sets of Bookmarks *** ;; ;; The best way to think about tags is as names of sets. All ;; bookmarks tagged
blue' constitute the bookmark set named blue'. ;; ;; The bookmarks visible in the bookmark list at any time also ;; constitute an unnamed set. Likewise, the marked bookmarks and the ;; unmarked bookmarks are unnamed sets. Bookmark+ is all about ;; helping you act on sets of Emacs objects. Bookmarks are named, ;; persistent pointers to objects such as files and filesets. ;; Bookmark tags are named, persistent sets of bookmarks (and hence ;; of their target objects). ;; ;; The marking commands make it easy to combine sets as unions or ;; intersections. And you can give the result a name for quick ;; access later, just by adding a new tag. in other words, do the ;; set-definition work only once, and name the result. ;; ;; How would you tag as
Java IDE Projects' the bookmarks that are
;; already tagged both Java' and
ide'?
;;
;; 1. T m * Java RET ide RET RET', to mark them. ;; 2.
T > + Java IDE Projects RET RET, to tag them.
;;
;; How would you sort your bookmarks, to show all those tagged both
;; blue' and
moon' first?
;;
;; 1. T m * blue RET moon RET RET', to mark them. ;; 2.
s >' to sort the marked bookmarks first
;; (see (@> "Sorting Bookmarks"), below).
;;
;; If you wanted to show only the marked bookmarks, instead of
;; sorting to put them first in the list, you would use >' ;; instead of
s >'.
;;
;; How would you query-replace the set of files that are tagged with
;; any of the tags alpha',
beta', and gamma', but are not tagged ;;
blue' or moon'? ;; ;; 1.
F S', to show only the file bookmarks.
;; 2. T m + alpha RET beta RET gamma RET RET', to mark the ;; bookmarks that have at least one of those tags. ;; 3.
T u + blue RET moon RET RET', to unmark those that are
;; tagged blue' or
moon'.
;; 4. M-q' to query-replace the marked files. ;; ;; If that were a set of files that you used often, then you would ;; name the set by giving the files a new tag. ;; ;; The point is that bookmarks, and bookmark tags in particular, let ;; you define and manipulate sets of Emacs objects. It doesn't ;; matter how you define such a set: regexp matching (marking, ;; filtering), by object type, by tag combinations... Sets need not ;; be named to act on them, but you can provide them with persistent ;; names (tags) to avoid redefining them over and over. Manipulation ;; of bookmarked objects includes visiting, searching, and ;; query-replacing. And you can define your own bookmark types ;; (using bookmark handlers) and associated manipulations. ;; ;; ;;(@* "Open Dired for the Marked File Bookmarks") ;; *** Open Dired for the Marked File Bookmarks *** ;; ;; You've seen that the bookmark list has many features that are ;; similar to Dired features. But Dired is specialized for files and ;; directories, and it has many more features for manipulating them. ;; The bookmark list is not intended to replace Dired. ;; ;; You can, however, use the bookmark list to take advantage of ;; arbitrary Dired features for file and directory bookmarks. ;; Command
bmkp-bmenu-dired-marked' (M-d >') weds Bookmark+'s ;; set-defining and set-manipulating features (tagging, marking, ;; filtering etc.) to Dired's file-manipulating features. ;; ;;
M-d >' opens a Dired buffer that is specialized for just the
;; files and directories whose bookmarks are marked in the bookmark
;; list. (Other marked bookmarks are ignored by the command.) The
;; files and directories can be located anywhere; they need not be in
;; the same directory. They are listed in Dired using absolute file
;; names.
;;
;; (In Emacs versions prior to release 23.2, only local files and
;; directories can be handled, due to Emacs bug #5478. In such
;; versions, remote-file bookmarks are ignored by M-d >'.) ;; ;; This Bookmark+ feature makes sets of files and directories ;; immediately amenable to all of the operations provided by Dired. ;; ;; It is particularly useful in conjunction with tags. Use bookmark ;; tags and marks to define a possibly complex set of file and ;; directory bookmarks. Then hit
M-d >' to list them in a Dired
;; buffer. Then use any Dired commands you want to act on any of
;; them.
;;
;; For example, to compress bookmarked files that are tagged with
;; both blue' and
moon':
;;
;; 1. Mark them using T m * blue RET moon RET RET'. ;; 2. Open Dired for them using
M-d >'.
;; 3. Mark them in Dired, then compress them using Z'. ;; ;; Since tags are persistent, Bookmark+ gives you a good way to ;; define an arbitrary set of files as a project and then open them ;; in Dired at any time to operate on them. ;; ;; If you use
Dired+' (library dired+.el'), then a similar feature ;; is available for the marked files and directories: You can use ;;
C-M-' in Dired to open a separate Dired buffer for them only.
;; You can of course then bookmark that resulting Dired buffer, if
;; you like.
;;
;; If you use Icicles', then whenever you use a command that reads a ;; file (or directory) name, you can use
M-|' during file-name
;; completion to open Dired on the currently matching set of file
;; names. That is, this is the same kind of special Dired buffer
;; that is provided for file and directory bookmarks by M-d >' in ;; the bookmark list. ;; ;; ;;(@* "Marking and Unmarking Bookmarks") ;; *** Marking and Unmarking Bookmarks *** ;; ;; Bookmark+ enhances the marking and unmarking of bookmarks in the ;; bookmark list in several ways. These enhancements are similar to ;; features offered by Dired and Dired-X. You can use: ;; ;; *
% m' to mark the bookmarks that match a regexp. The entire
;; line in the bookmark list is checked for a match, that is, both
;; the bookmark name and the file name, if shown.
;;
;; * M-DEL' (or
U') to unmark all bookmarks, or all that are marked
;; >', or all that are flagged
D' for deletion.
;;
;; * t' to toggle (swap) the marked and unmarked bookmarks: those ;; that are marked become unmarked, and vice versa. ;; ;; *
>' to show only the marked bookmarks or <' to show only the ;; unmarked bookmarks. Repeat to show them all again. ;; ;; *
F M', I M' etc. to mark only the file bookmarks, Info ;; bookmarks etc. (The first key here is the same as the ;; corresponding filter key, e.g.
F' for files - see next topic.)
;;
;; * O M' to mark the orphaned bookmarks, that is, those whose ;; recorded files have been renamed or deleted. You can then ;; relocate or delete the bookmarks, as appropriate. ;; ;; ;;(@* "Filtering Bookmarks (Hiding and Showing)") ;; *** Filtering Bookmarks (Hiding and Showing) *** ;; ;; There are three ways to show only certain bookmarks. ;; ;; 1. Filter by bookmark type. ;; ;; 2. Filter bookmarks incrementally and temporarily, using pattern ;; matching. ;; ;; 3. Filter out the marked or unmarked bookmarks. ;; ;; * Filtering by bookmark type ;; ;; The commands that show only bookmarks of a particular type are ;; bound to keys that end in
S' (for "show"). For example, I S' ;; shows only Info bookmarks, and
X S' shows only temporary
;; bookmarks.
;;
;; The type filter is reflected in the bookmark-list display title.
;; It says All Bookmarks' if no type filter is used. Otherwise it ;; tells you what kind of bookmarks are listed:
Autonamed
;; Bookmarks', File and Directory Bookmarks', and so on. ;; ;; Note: It is only filtering by bookmark type that is remembered ;; when you save a bookmark-list display state or you create a ;; bookmark-list bookmark. See (@> "State-Restoring Commands and Bookmarks"). ;; ;; * Filtering incrementally by pattern matching ;; ;; These commands show only bookmarks that in some way match a ;; pattern (regexp) that you type. The bookmarks are filtered ;; incrementally as you type the pattern. Hit any non-inserting ;; key, such as
RET', to finish defining the pattern.
;;
;; The commands for this are bound to keys that start with P' (for ;; "pattern"). For example,
P B' shows only bookmarks whose names
;; match the regexp, P F' shows those whose file names match,
P
;; A' shows those whose annotations match, and P T' shows those ;; that have one or more tags that match. (See (@> "Bookmark Tags"), ;; above, for information about tags.) ;; ;; * Filtering based on marking ;; ;; Just as in Dired, you can use
% m' to mark the bookmarks that
;; match a regexp. Then use >' to show only the marked bookmarks. ;; See (@> "Marking and Unmarking Bookmarks"), above. ;; ;; This method has the advantage that you can show the complement, ;; the bookmarks that do *not* match the regexp, by using
<'
;; instead of >'. It also has the advantage that matching checks ;; the combination of bookmark name and file name (use
M-t' to
;; toggle showing file names).
;;
;;
;;(@* "Only Visible Bookmarks Are Affected")
;; *** Only Visible Bookmarks Are Affected ***
;;
;; Commands that operate on the current bookmark or on the marked or
;; the unmarked bookmarks act only on bookmarks that are displayed
;; (not hidden). This includes the commands that mark or unmark
;; bookmarks. This means that you can easily define any given set of
;; bookmarks.
;;
;; For example:
;;
;; Use F S' to show only bookmarks associated with files. ;; Use
% m' to mark those that match a particular regexp.
;; Use R S' to show only bookmarks that have regions. ;; Use
m' to mark some of those region bookmarks individually.
;; Use .' to show all bookmarks. ;; Use
t' to swap marked and unmarked (so unmarked are now marked)
;; Use `D' to delete all of the marked bookmarks (after confirming)
;;
;; Together, steps 1-7 delete all file bookmarks that match the
;; regexp and all region bookmarks that you selectively marked.
;;
;;
;;(@ "Omitting Bookmarks from Display")
;; *** Omitting Bookmarks from Display ***
;;
;; In sections (@> "Marking and Unmarking Bookmarks") and
;; (@> "Filtering Bookmarks (Hiding and Showing)") you learned how
;; to hide and show bookmarks in the bookmark list. This section is
;; about a different kind of hiding, called "omitting".
;;
;; Omitted bookmarks are not shown in the bookmark list, no matter
;; what filtering is used. The only way to show omitted bookmarks is
;; to show all of them and only them, using - S', which is bound to ;; command
bmkp-bmenu-show-only-omitted'.
;;
;; Omitted bookmarks are still available even if they are not shown,
;; and you can still jump to them (e.g. using C-x r b'). You just ;; don't see them in the bookmark list. And that's the reason for ;; this feature: to hide those bookmarks that you don't care to see. ;; ;; One use for this feature is to hide the component bookmarks that ;; make up a sequence bookmark (see ;; (@> "Function, Sequence, Variable-List,... Bookmarks")). The ;; default behavior when you create a sequence bookmark is in fact to ;; omit its component bookmarks from the displayed list. ;; ;; You can omit any bookmarks by marking them and then using
- >'
;; (bmkp-bmenu-omit/unomit-marked'). If you are looking at the ;; omitted bookmarks (after using
- S'), then - >' un-omits the ;; bookmarks marked there. Think of two complementary spaces: the ;; normal bookmark list and the omitted bookmark list. When you use ;;
- >', the marked bookmarks that are currently shown are moved to
;; the opposite space.
;;
;; You can un-omit all of the omitted bookmarks at once, using - U' ;; (
bmkp-unomit-all'). You can also call this command from outside
;; the bookmark-list display.
;;
;; Omitted bookmarks that are marked are generally not included when
;; you use a command that acts on the marked bookmarks. However, if
;; you use a negative prefix argument with the command then they are.
;;
;; For some commands this is relaxed so that any prefix arg has this
;; effect. For other commands a non-negative prefix arg has a
;; different effect. In some cases, a non-negative prefix arg has
;; one effect and a non-positive prefix arg has the effect of
;; including omitted marked bookmarks, so that a zero prefix arg has
;; both effects. For any given command, consult the doc string for
;; full information.
;;
;;
;;(@* "Sorting Bookmarks")
;; *** Sorting Bookmarks ***
;;
;; Filtering hides certain kinds of bookmarks. Sometimes, you want
;; to see bookmarks of various kinds, but you want them to be grouped
;; or sorted in different ways, for easy recognition, comparison, and
;; access.
;;
;; Bookmarks shown in the bookmark list are sorted using the current
;; value of option bmkp-sort-comparer'. (If that is
nil', they are
;; unsorted, which means they appear in reverse chronological order
;; of their creation.)
;;
;; You can use s s'... (repeat hitting the
s' key) to cycle among
;; the various sort orders possible, updating the display
;; accordingly. By default, you cycle among all available sort
;; orders, but you can shorten the cycling list by customizing option
;; bmkp-sort-orders-for-cycling-alist'. ;; ;; You can also change directly to one of the main sort orders ;; (without cycling) using
s >', s n',
s f n', etc. There are
;; many such predefined sort orders bound to keys with the prefix s' ;; - use
C-h m' or ?' for more info. ;; ;;
s >' – Sort marked (>') before unmarked ;;
s *' – Sort modified (*') before unmodified ;;
s 0' – Sort by bookmark creation date/time
;; s b' – Sort by last buffer or file access ;;
s a' – Sort annotated (a') before unannotated ;;
s d' – Sort by last bookmark access date/time
;; s D' – Sort flagged (
D') before unflagged
;; s f d' – Sort by last local file access date/time ;;
s f k' – Sort by local file kind: file, symlink, dir
;; s f n' – Sort by file name ;;
s f s' – Sort by local file size
;; s f u' – Sort by last local file update (edit) date/time ;;
s g' – Sort by Gnus thread: group, article, message.
;; s i' – Sort by Info manual, node, position ;;
s k' – Sort by bookmark type (kind)
;; s n' – Sort by bookmark name ;;
s t' – Sort tagged (t') before untagged ;;
s v' – Sort by visit frequency
;;
;; You can reverse the current sort direction (ascending/descending)
;; using s r'. Also, repeating any of the main sort-order commands ;; (e.g.
s n') cycles among that order, the reverse, and unsorted.
;;
;; For a complex sort, which involves composing several sorting
;; conditions, you can also use s C-r' to reverse the order of ;; bookmark sorting groups or the order within each group (depending ;; on whether
s r' is also used). Try it, for example, together
;; with sorting by bookmark kind (s k'). ;; ;; Be aware that
s C-r' can be a bit unintuitive. If it does not do
;; what you expect or want, or if it confuses you, then don't use it
;; ;-). (s C-r' has no noticeable effect on simple sorting.) ;; ;; Remember that you can combine sorting with filtering different ;; sets of bookmarks - bookmarks of different kinds (e.g. Info) or ;; bookmarks that are marked or unmarked. ;; ;; Finally, you can easily define your own sorting commands and sort ;; orders. See macro
bmkp-define-sort-command' and the
;; documentation for option bmkp-sort-comparer'. (Bookmark+ uses ;; option
bmkp-sort-comparer'; it ignores vanilla Emacs option
;; bookmark-sort-flag'.) ;; ;; Of particular note is that you can interactively define commands ;; that sort by a given list of tags - you use keys
T s' (command
;; bmkp-define-tags-sort-command') to do that. You are prompted for ;; the tags to sort by. Bookmarks are sorted first according to ;; whether they are tagged with the first tag, then the second tag, ;; and so on. Otherwise, sorting is by bookmark name. ;; ;; The tags you specify are used, in order, in the name of the new ;; command. For example, if you enter tags
alpha', beta', and ;;
gamma', in that order, then the sorting command created is
;; bmkp-bmenu-sort-alpha-beta-gamma'. The new command is saved in ;; your bookmark commands file (
bmkp-bmenu-commands-file').
;;
;; Note that because you can add a new tag to all bookmarks that have
;; some given set of tags, you can use that single (new) tag to
;; represent the entire tag set. Sorting by that tag is then the
;; same as sorting by the tag set. You can of course use overlapping
;; sets in the composite sort command. You can, for example, sort
;; first according to tag tag1', which represents the set of tags ;;
alpha', beta',
gamma', delta', and then sort according to tag ;;
tag2', which represents the set of tags beta',
delta'.
;;
;; See also (@> "Use Bookmark+ with Icicles") - the same technique is
;; used in `Icicles' for sorting bookmarks as completion candidates.
;;(@* "Bookmarks for Specific Files or Buffers")
;; ** Bookmarks for Specific Files or Buffers **
;;
;; A bookmark typically records a position or a region in a file or
;; buffer. Sometimes you are interested in accessing or examining
;; only the bookmarks for particular files or buffers. For example,
;; you might want to navigate among the bookmarks for the current
;; buffer. Or you might want to search the regions recorded in the
;; bookmarks for a particular file.
;;
;; For a bookmark, the recorded file and buffer name differ in that
;; the file name is absolute. Bookmarks for buffer foo.el' include ;; all files named
foo.el', whereas bookmarks for file
;; /project1/lisp/foo.el' include only the files in that one ;; directory. ;; ;; Another important difference is that when multiple buffers visit ;; different files that have the same relative file name (i.e., in ;; different directories), Emacs makes the buffer names unique by ;; appending
' as needed, where N' is 2, 3,... When you create ;; a bookmark, the current buffer name is recorded as the bookmark's ;; buffer. If the current buffer is not visiting a file, then the ;; bookmark created is a non-file bookmark. In that case, to use the ;; bookmark later you must have a buffer of the same name ;; (e.g.
foo.el<2>').
;;
;; Bookmark+ provides commands to handle these different use cases:
;; specific files and specific buffers. The keys bound to these
;; commands use f' for file and
b' for buffer. In the
;; bookmark-list display, the following keys affect the bookmarks for
;; a particular file or buffer whose name you provide (with
;; completion).
;;
;; * = f M' and
= b M' - mark
;; * = f S' and
= b S' - show (only)
;;
;; For navigation, the following keys jump to bookmarks for
;; particular files or buffers. (Use C-x 4 j' for other-window.) ;; ;; *
C-x j ,,' - current buffer
;; * C-x j = f' and
C-x j = b' - specified file(s) or buffer(s)
;;
;; For the =' keys you are prompted for one or more file names or ;; buffer names. ;; ;; Finally, because the bookmarks in the current buffer can be of ;; particular interest,
C-x x ,' opens the bookmark-list display for
;; only those bookmarks. (`,' stands generally for "this-buffer" in
;; Bookmark+ key bindings.)
;;(@* "Cycling, Navigation List")
;; ** "Cycling, Navigation List" **
;;
;; Using completion to jump to a bookmark is handy. It lets you
;; choose a bookmark by its name and gives you direct ("random")
;; access to it.
;;
;; Sometimes, however, you don't much care what a bookmark is named,
;; and you want to cycle quickly among relatively few, related
;; bookmarks. Obviously, the smaller the number of bookmarks in the
;; set, the more convenient cycling is - with many bookmarks cycling
;; can become tedious.
;;
;; An analogy: If your TV has lots of channels, then the channel
;; up/down buttons on the remote control are not so useful: 32, 33,
;; 34, ..., 79! Unless the channel you want happens to be near the
;; current channel, cycling around a huge ring of channels is not the
;; way to go. And just because your TV receives lots of channels
;; does not mean that you watch them all or that you are equally
;; interested in them all.
;;
;; Some TV remote controls have a feature that mitigates this
;; problem. You can define a ring of favorite channels, and there
;; are two additional buttons that let you cycle forward and backward
;; around the ring, skipping the channels in between. The number of
;; favorites is relatively small, so cycling is not tedious. More
;; importantly, all of the channels in the ring are ones you are
;; interested in.
;;
;; Extend this idea to allow for assigning different sets of channels
;; to the favorites ring at different times: choose the ring you want
;; at any time: sports, music, films, science, art, history, and so
;; on. Add the possibility of sorting those sets in various ways, to
;; further facilitate cycling, and you arrive at the idea behind the
;; Bookmark+ navigation list.
;;
;; Another analogy is a music playlist. You can use Bookmark+ as a
;; simple music player by bookmarking music files. Similarly, you
;; can use Bookmark+ to create slideshows by bookmarking image files.
;; Cycle the navigation list to move through the slide show.
;;
;; If you use MS Windows, you can take advantage of your existing
;; file associations to open your bookmarks using the appropriate
;; program - no need to define a new bookmark type and handler. See
;; (@> "Bookmarking Files That You Cannot Visit with Emacs").
;;
;; Note: The default value of option bmkp-use-region' is
t', not
;; cycling-too', which means that when you cycle to a bookmark its ;; recorded region (if any) is not activated. This is probably what ;; you want most of the time. Cycling is a repetitive action, and if ;; you cycle to a bookmark with no recorded region then an already ;; active region is just extended. Customize the value to ;;
cycling-too' if you prefer that behavior.
;;
;;
;;(@* "The Bookmark Navigation List")
;; *** "The Bookmark Navigation List ***
;;
;; Bookmark+ is all about letting you define and manipulate sets of
;; bookmarks. When a bookmark set can be used for cycling (as well
;; as jumping) it is called the "navigation list" or "navlist", for
;; short.
;;
;; In other words, Bookmark+ lets you cycle among any set of
;; bookmarks. When you cycle, it is the set that currently
;; constitutes the navigation list that is cycled.
;;
;; Here are two ways to define the navigation list:
;;
;; * C-x x :' (
bmkp-choose-navlist-of-type') - As the set of all
;; bookmarks of a certain type (any' or empty input means use all ;; bookmarks). ;; ;; *
C-x x B' (bmkp-choose-navlist-from-bookmark-list') - As the ;; set of all bookmarks corresponding to a bookmark-list bookmark, ;; that is the bookmarks corresponding to a given recorded state of ;; buffer
Bookmark List'.
;;
;; Each of these lets you choose a set of bookmarks using completion.
;; For C-x x :' you are prompted for the type of bookmark ;; (e.g.
dired').
;;
;; For C-x x B' you are prompted for the name of a bookmark-list ;; bookmark that you created. But you can also choose the candidate ;;
CURRENT Bookmark List' to capture the bookmarks that would be
;; shown currently in the *Bookmark List*' (even if the list is not ;; displayed now). See (@> "State-Restoring Commands and Bookmarks") ;; for information about bookmark-list bookmarks. ;; ;; If you do not define the navigation list before you start cycling, ;; it is automatically defined as follows: ;; ;; * If you cycle using a current-file/buffer cycling key such as ;;
C-x x down' (see (@> "Cycling in the Current File/Buffer"))
;; then the bookmarks in the current file or buffer are used as the
;; navlist.
;;
;; * Otherwise, a snapshot is taken of the the bookmarks currently in
;; the global bookmark list (the value of variable
;; bookmark-alist') as the navlist. ;; ;; However the navlist is defined, it is important to remember this: ;; it is a static snapshot of some set of bookmarks taken at a given ;; time. Subsequent changes to the bookmark list that was copied are ;; not reflected in the navlist. If you add a bookmark it will not ;; be among those cycled. But see also ;; (@> "Cycling Dynamic Sets of Bookmarks") for how to cycle dynamic ;; sets. ;; ;; You can update the navlist at any time by taking another snapshot ;; of the same bookmark list you used for the last snapshot. For the ;; global bookmark list just use
C-x x : RET'. (You can of course
;; bind that action to a shorter key sequence if you like.)
;;
;; Besides cycling among the bookmarks of the navlist (see next),
;; once you have defined the navigation list you can use C-x j N' or ;;
C-x 4 j N' to jump to its bookmarks, as mentioned in section
;; (@> "Different Types of Jump Commands").
;;
;; Note that just because you might have used C-x x B' to define the ;; navlist using a particular bookmark-list bookmark or the current ;;
Bookmark List' state, that does not mean that the *Bookmark ;; List*' state at any given time necessarily reflects the navlist ;; bookmarks. The two are separate. You can, however, open the ;;
Bookmark List' so that it reflects the bookmarks currently in
;; the navigation list, using C-x x N' (
bmkp-navlist-bmenu-list').
;;
;;
;;(@* "Cycling the Navigation List")
;; *** "Cycling the Navigation List" ***
;;
;; So you choose a navigation list. How do you then cycle among its
;; bookmarks?
;;
;; Commands bmkp-next-bookmark' and
bmkp-previous-bookmark' cycle
;; to the next and previous bookmark in the navigation list (with
;; wraparound). (There are also other-window versions of these
;; commands.)
;;
;; You can bind these to any keys you like, but it's obviously better
;; to choose keys that are easily repeatable (e.g. by holding them
;; pressed). Some people who are used to using MS Visual Studio
;; might want to use f2' and
S-f2' to cycle forward and backward.
;;
;; Bookmark+ does not define such key bindings, but you can. What it
;; does is define repeatable keys on the bookmark-map' keymap, which ;; by default has prefix
C-x x'. To do this it binds similar
;; commands that can be repeated by simply repeating the key-sequence
;; suffix. These are the (default) keys:
;;
;; Forward: C-x x f',
C-x x C-f', C-x x right' ;; Backward:
C-x x b', C-x x C-b',
C-x x left'
;;
;; (If you use an Emacs version prior to Emacs 22, you cannot use
;; this prefix-key repeatable feature.)
;;
;; In addition, if you use MS Windows then you can invoke the Windows
;; Open' action on each bookmark when you cycle, to act on its file ;; using the program associated with the file type. This lets you ;; play music or display images in a playlist or slideshow fashion. ;; These are the keys to do that: ;; ;; Forward:
C-x x next' (PageDown key)
;; Backward: C-x x prior' (PageUp key) ;; ;; Being able to cycle among an arbitrary set of bookmarks is the ;; most important feature of Bookmark+ cycling. The other important ;; feature is that if the navigation list is defined by
Bookmark
;; List' then the characteristics of that bookmark display are
;; respected for navigation. Only the bookmarks visible in
;; *Bookmark List*' are included, and the
Bookmark List' sort
;; order is used for navigation.
;;
;; So you can not only choose any set of bookmarks for cycling at any
;; given time, you can also cycle among them in an order you choose.
;; For example, if in the bookmark list display (C-x x e' or
C-x r
;; l') you show only those file bookmarks that belong to a given
;; project, and you have them sorted by file size, then cycling moves
;; among only those files, in file-size order.
;;
;; This is a main reason you will want to define bookmark-list
;; bookmarks, which record a specific set of bookmarks and their sort
;; order: to later choose given sets in different contexts for
;; cycling.
;;
;;
;;(@* "Cycling Dynamic Sets of Bookmarks")
;; *** "Cycling Dynamic Sets of Bookmarks" ***
;;
;; The fact that the navlist is a static snapshot is a useful
;; feature, but sometimes you might want to cycle among a particular
;; dynamic set of bookmarks, that is, to have cycling take changes to
;; the bookmark set into account automatically. For that, Bookmark+
;; provides separate cycling commands for most types of bookmark.
;;
;; By default, these different kinds of cycling commands are not
;; bound to any keys, with the exception of the commands for cycling
;; the current fle or buffer. This exception includes cycling all
;; bookmarks for the current file/buffer
;; (see (@> "Cycling in the Current File/Buffer")
;; and cycling only the highlighted bookmarks for the current
;; file/buffer (see (@> "Using Highlighted Bookmarks")). Keys C-x x ;; down' and
C-x x C-down' are defined for these two kinds of
;; current-buffer cycling.
;;
;; If you often want to cycle among the bookmarks of some other
;; particular kind (e.g. only the autonamed bookmarks), then you can
;; bind the relevant commands
;; (e.g. bmkp-next-autonamed-bookmark-repeat', ;;
bmkp-previous-autonamed-bookmark-repeat', or their other-window
;; versions) to handy keys. Otherwise, you can just use the cycling
;; commands without binding them.
;;
;;
;;(@* "Cycling in the Current File/Buffer")
;; *** "Cycling in the Current File/Buffer" ***
;;
;; You can navigate the bookmarks in the current file or buffer by
;; cycling as well as jumping. It is convenient to have dedicated
;; keys for this, separate from the keys to cycle the navigation
;; list. The following keys are defined, corresponding to commands
;; bmkp-next-bookmark-this-file/buffer-repeat' and ;;
bmkp-previous-bookmark-this-file/buffer-repeat':
;;
;; Next: C-x x n',
C-x x C-n', C-x x down' ;; Previous:
C-x x p', C-x x C-p',
C-x x up'
;;
;; Starting with Emacs 23.3 (Emacs fix for bug #6256), you can also
;; use the mouse wheel to cycle: C-x x' then just rotate the wheel. ;; ;; Again, you can bind any keys you want to these commands ;; (e.g.
f2', S-f2'). If you do not need to use a prefix key, then ;; bind commands
bmkp-next-bookmark-this-file/buffer' and
;; bmkp-previous-bookmark-this-file/buffer' (no -repeat). ;; ;; You can also cycle among just the highlighted bookmarks in the ;; current file or buffer - see (@> "Using Highlighted Bookmarks"). ;; ;; Cycling among bookmarks for the current file or buffer (whether ;; all or only the highlighted ones) is dynamic: the current set of ;; bookmarks is cycled, not a static snapshot taken at some point in ;; past. The navlist is automatically updated to the current dynamic ;; set each time you cycle. This is different from the usual cycling ;; of the navlist, where it is taken as a static snapshot - ;; see (@> "The Bookmark Navigation List"). ;; ;; By default, you cycle among the bookmarks for the current file or ;; buffer in order of their buffer positions, top to bottom. If you ;; want a different order, you can customize option ;;
bmkp-this-file/buffer-cycle-sort-comparer'.
;;
;; Alternatively, you can use C-x x ,' to display the
Bookmark
;; List' with only the current file/buffer's bookmarks, sort them
;; there, and then use C-x x B' to set the navigation list to ;;
CURRENT Bookmark List'. In that case, you use the navlist
;; cycling keys (e.g. C-x x f', not
C-x x n'), and the cycled set
;; is a static snapshot.
;;
;; Note that the keys mentioned here cycle bookmarks for the current
;; file if visiting a file, or the current buffer otherwise. There
;; are also commands (unbound to keys) for cycling bookmarks for the
;; current file only or the current buffer only.
;;
;; The bookmarks for the current buffer are those that were created
;; in a buffer of exactly the same name. If one buffer visits a file
;; foo.el', and another buffer visits a different file of the same ;; name (i.e., in a different directory), the second buffer will have ;; the name
foo.el<2>'. The buffer name is recorded when you create
;; a bookmark. If you later use same-buffer cycling then the
;; bookmarks cycled are only those created with the same buffer name
;; as the current buffer.
;;
;; This is the reason why the `-file/buffer' commands are bound to
;; keys. They are usually what you want. They try first to work
;; with bookmarks for the same file as the current buffer, if it is
;; visiting a file.
;;(@* "Autonamed Bookmarks - Easy Come Easy Go")
;; ** "Autonamed Bookmarks - Easy Come Easy Go" **
;;
;; Sometimes it is convenient to quickly create and delete bookmarks
;; whose names you don't really care about. That is the purpose of
;; "autonamed" bookmarks. An autonamed bookmark has a simple name
;; provided automatically, and it does not record any region
;; information - it records only a position. An autonamed bookmark
;; is nevertheless an ordinary, persistent bookmark.
;;
;; C-x x RET' creates a bookmark at point without prompting you for ;; the name. It is named using the current buffer name preceded by ;; the position in the buffer. For example, the default name of the ;; autonamed bookmark in buffer
foo.el' at position 58356 is
;; 000058356 foo.el'. ;; ;; When you jump to any bookmark, the actual destination can differ ;; from the recorded position, because the buffer text might have ;; changed. In that case, the position you jump to has been ;; automatically relocated using the recorded bookmark context (some ;; buffer text surrounding the original position). ;; ;; If option
bmkp-save-new-location-flag' is non-nil' then, after ;; jumping, the recorded position of the bookmark is automatically ;; updated to reflect the new location jumped to. This is true for ;; any bookmark. ;; ;; In the case of an autonamed bookmark, the bookmark name typically ;; reflects the recorded position when you create it. And when you ;; jump to it, both the name and the recorded position are updated to ;; reflect the jump destination. So jumping to an autonamed bookmark ;; keeps its persistent record in sync with the buffer location. ;; ;; You will thus notice that the names of autonamed bookmarks can ;; change as you visit them (e.g. cycling). The bookmarks are ;; automatically repositioned following their recorded contexts, and ;; their names reflect that repositioning. ;; ;; It is only when you jump to a bookmark that it is repositioned ;; this way, and only if needed. It is normal that some bookmarks ;; become somewhat out of sync with their original positions as you ;; edit the text in the buffer. In addition, if you highlight ;; bookmarks then you will notice the highlighting move as you edit ;; nearby text. The recorded bookmark has not changed, but its ;; highlight has moved. The highlight moves more or less as if it ;; were an Emacs marker. When you jump to the bookmark and it is thus ;; updated, the highlight moves back to the recorded position, ;; adjusted perhaps to fit the recorded context. ;; ;;
C-x x RET' is bmkp-toggle-autonamed-bookmark-set/delete', and it ;; does double duty. If an autonamed bookmark is under the cursor, ;; then
C-x x RET' deletes it. Easy creation, easy deletion.
;; Because of this toggle behavior, there is at most one autonamed
;; bookmark at any given buffer position.
;;
;; C-x x RET' has a third use: With a prefix argument, it prompts ;; you to confirm the deletion of *ALL* autonamed bookmarks for the ;; current buffer. ;; ;; (You can also use
C-x x delete' (that's the delete' key), bound ;; to
bmkp-delete-bookmarks', to delete individual bookmarks under
;; the cursor or all bookmarks in the buffer. This is not limited to
;; autonamed bookmarks.)
;;
;; In addition to C-x x RET', you can create autonamed bookmarks ;; using these commands: ;; ;; *
bmkp-set-autonamed-bookmark-at-line' - At a line beginning
;; * bmkp-set-autonamed-regexp-buffer' - At buffer matches ;; *
bmkp-set-autonamed-regexp-region' - At region matches
;; * bmkp-occur-create-autonamed-bookmarks' (
C-c b' in *Occur*') - ;; At
occur' and multi-occur' hits ;; ;; Autonamed bookmarks are normal bookmarks. In particular, they are ;; persisted. If you do not care to persist them, you can ensure ;; that they are automatically deleted by adding ;;
bmkp-delete-autonamed-this-buffer-no-confirm' to
;; kill-buffer-hook' and
bmkp-delete-autonamed-no-confirm' to
;; kill-emacs-hook': ;; ;; (add-hook 'kill-buffer-hook ;; 'bmkp-delete-autonamed-this-buffer-no-confirm) ;; (add-hook 'kill-emacs-hook ;; 'bmkp-delete-autonamed-no-confirm) ;; ;; You can customize the format of autonamed bookmarks using options ;;
bmkp-autoname-bookmark-function' and bmkp-autoname-format'. ;; ;; For example, if you want autonamed bookmarks to show the line and ;; column numbers, in the form
L,C ', where
;; is a sequence of decimal digits and is the buffer name,
;; then you can use a function such as this as the value of
;; bmkp-autoname-bookmark-function': ;; ;; (defun my-auto-l+c-name (position) ;; "Return a name for POSITION that uses line & column numbers." ;; (let ((line (line-number-at-pos position)) ;; (col (save-excursion ;; (goto-char position) (current-column)))) ;; (format "L%d,C%d %s" col line (buffer-name)))) ;; ;; To enable Bookmark+ to recognize such bookmarks as autonamed, you ;; would then set
bmkp-autoname-format' to the format specification
;; "^L[0-9]+,C[0-9]+ %B", to match their names. Here, the %B' is a ;; Bookmark+ format specifier that corresponds to the buffer name. ;; ;; Recognizing the buffer name in an autonamed bookmark is important ;; or commands that act only on autonamed bookmarks for a specific ;; buffer. That includes commands
bmkp-autonamed-this-buffer-jump'
;; and bmkp-delete-all-autonamed-for-this-buffer'. ;; ;; You use the special format specifier
%B' for the buffer name,
;; instead of just %s', because the format can have multiple
%'
;; sequences, and the buffer name could be anywhere in the bookmark
;; name. Depending on the buffer, the buffer name could thus be
;; confused with other text in the bookmark name, unless you use %B' ;; to show where it is. You can use just
%s' for it if there is no
;; risk of ambiguity. (Use %s' in
bmkp-autoname-bookmark-function'
;; to insert the buffer name.)
;;(@* "Temporary Bookmarks")
;; ** Temporary Bookmarks **
;;
;; Autonamed bookmarks are easy-come-easy-go in the sense that C-x x ;; RET' either sets (creates) one or deletes the one under the ;; cursor. But what about temporary bookmarks in general? What if ;; you want only bookmarks that are temporary, that is, not saved to ;; disk? Or what if you want certain kinds of bookmarks to always be ;; temporary? Or what if you want to toggle whether particular ;; bookmarks get saved automatically? ;; ;; ;;(@* "Temporary Bookmarking Mode") ;; *** Temporary Bookmarking Mode *** ;; ;; As always, you can control whether the bookmarks in the current ;; bookmark list are saved automatically using option ;;
bookmark-save-flag'. Remember that you can toggle this option
;; using command bmkp-toggle-saving-bookmark-file' (bound to
M-~'
;; in the bookmark-list buffer). Remember too that you can at any
;; time change the set of available bookmarks (the bookmark list),
;; which means also changing the set of bookmarks that are
;; susceptible to being saved.
;;
;; You could, for example:
;;
;; 1. Use C-x x 0' (
bmkp-empty-file') to create a new, empty
;; bookmark file.
;;
;; 2. Use C-x x L' (
bmkp-switch-bookmark-file-create') to switch to
;; using that new, empty bookmark file.
;;
;; 3. Use M-x bmkp-toggle-saving-bookmark-file' to turn off ;; auto-saving bookmarks to disk. ;; ;; This is essentially what the minor-mode toggle command ;;
bmkp-temporary-bookmarking-mode' does. When in this minor mode,
;; bookmarks that you create are stored on the new bookmark list,
;; which is not automatically saved to disk. If you do not
;; explicitly save it yourself then the bookmarks are lost when your
;; Emacs session ends - they are only temporary.
;;
;; This command is bound to M-L' in the bookmark-list display buffer ;; (
Bookmark List'). The suffix L' indicates that this has to do ;; with loading a bookmark file. See (@> "Using Multiple Bookmark Files"). ;; ;; In the bookmark-list display, temporary bookmarking mode is ;; indicated in the mode line by
TEMPORARY Bookmarking' in place of
;; Bookmarks' as the mode name. ;; ;; ;;(@* "Making Bookmarks Temporary") ;; *** Making Bookmarks Temporary *** ;; ;; Instead of simply switching to a temporary bookmark list, so that ;; *all* bookmarking is only temporary, you more often want to have ;; some bookmarks be temporary while still ensuring that others get ;; saved. Or you temporarily want all new bookmarks that you create ;; and all bookmarks that you update to be temporary, without ;; affecting other, unchanged bookmarks. ;; ;; You can control this at the level of individual bookmarks, types ;; of bookmarks, or all bookmarks whenever they are set (created or ;; updated). ;; ;; * At the individual-bookmark level, commands ;;
bmkp-make-bookmark-temporary' and bmkp-make-bookmark-savable' ;; prompt you for a bookmark name and then set its ;; temporary/savable status. Command ;;
bmkp-toggle-temporary-bookmark' combines these commands,
;; toggling the status for a given bookmark.
;;
;; In the bookmark list, this toggle is bound to C-M-X'. There ;; are also commands in the bookmark-list display to toggle the ;; temporary/savable status of the marked bookmarks (
M-X'), to
;; mark the temporary bookmarks (X M'), and to show only the ;; temporary bookmarks (
X S').
;;
;; * At the bookmark-type level, you can customize user option
;; bmkp-autotemp-bookmark-predicates'. It is a list of bookmark ;; predicates - typically type predicates - that define which ;; bookmarks are automatically made temporary whenever they are ;; set. ;; ;; The default value includes the type predicates for autonamed ;; bookmarks:
bmkp-autonamed-bookmark-p' and
;; bmkp-autonamed-this-buffer-bookmark-p'. This means that (only) ;; autonamed bookmarks are made temporary whenever they are created ;; or updated. ;; ;; The doc string for the option lists the predefined bookmark type ;; predicates, but you can use any bookmark predicates. ;; ;; * Finally, you can toggle whether *all* bookmarks become temporary ;; whenever they are created or updated, using command ;;
bmkp-toggle-autotemp-on-set', which is bound globally to C-x x ;; x'. ;; ;; You can delete all such temporary bookmarks from the current ;; bookmark list using command
bmkp-delete-all-temporary-bookmarks'
;; (or by using X M' to mark them in the bookmark-list display and ;; then hitting
D' to delete thems).
;;
;; In the bookmark-list display (buffer *Bookmark List*'), temporary ;; bookmarks are indicated with the mark
X' in the same column where
;; the annotation mark `a' would otherwise appear.
;;(@* "Automatic Bookmarking")
;; ** Automatic Bookmarking **
;;
;; You might find automatic bookmarking useful. The idea is that
;; Emacs sets a bookmark for you automatically.
;;
;; Bookmark+ can do this either when you perform some action (besides
;; explicitly bookmarking) or whenever you are idle for a given
;; period of time (option bmkp-automatic-bookmark-mode-delay'). ;; ;; ;;(@* "Automatic Bookmarking Using a Hook") ;; *** Automatic Bookmarking Using a Hook *** ;; ;; To automatically set a bookmark whenever some hook is run, put ;; function
bmkp-set-automatic-bookmark' on the hook. For example,
;; to set a bookmark at a definition jumped to whenever you use
;; Imenu, you can do this:
;;
;; (add-hook 'imenu-after-jump-hook #'bmkp-set-automatic-bookmark)
;;
;; The bookmark is an autonamed bookmark (see
;; (@> "Autonamed Bookmarks - Easy Come Easy Go")).
;;
;;
;;(@* "Automatic Idle-Period Bookmarking")
;; *** Automatic Idle-Period Bookmarking ***
;;
;; Automatic idle-period bookmarking creates bookmarks at spots where
;; you spend some time (idly). It uses
;; bmkp-set-automatic-bookmark', so the bookmarks created are ;; autonamed (see (@> "Autonamed Bookmarks - Easy Come Easy Go")). ;; ;; How many such bookmarks would you want? And how close together? ;; Bookmark+ tries to provide some user options that let you get the ;; behavior you want. Except for ;;
bmkp-automatic-bookmark-mode-delay' they apply to
;; bmkp-set-automatic-bookmark', so they affect both idle-period ;; bookmarking and automatic bookmarking on a hook. ;; ;; In general, you probably don't want such bookmarks to be created ;; too often or too close together. You probably don't care about ;; the names of the bookmarks created, and you don't want to be ;; interrupted to have to name them. You probably want automatic ;; idle-period bookmarking to be per-buffer, but you might sometimes ;; want to turn it on or off for all buffers. You might want more ;; than one automatic bookmark on a given line, but probably not. ;; Finally, you might or might not want such bookmarks to be ;; temporary (current session only) or highlighted. ;; ;; Mode
bmkp-automatic-bookmark-mode' is a local minor mode, which
;; means that it is buffer-specific. The command of the same name
;; turns the mode on and off. When the mode is on, the minor-mode
;; indicator ("lighter") Auto-Bmk' is shown in the mode line for the ;; buffer. You can customize this indicator (removing it, if you ;; like), using option
bmkp-automatic-bookmark-mode-lighter'.
;;
;; Command bmkp-global-automatic-bookmark-mode' turns on the mode in ;; all buffers, that is, it is global, not local. Regardless of ;; whether you use the mode locally or globally, a bookmark is ;; created automatically only in the current buffer. That is, a ;; buffer must be current (selected) for an automatic bookmark to be ;; created there - it's not enough that the mode be enabled in the ;; buffer. ;; ;; Option
bmkp-automatic-bookmark-set-function' defines the
;; bookmark-setting function. By default, its value is
;; bmkp-set-autonamed-bookmark-at-line', which sets an autonamed ;; bookmark at (the beginning of) the current line. If you want ;; bookmarks to be created automatically then you typically want them ;; to be autonamed, both because the name is unimportant and because ;; setting an autonamed bookmark requires no interaction on your ;; part. But you can use any setting function you like as the option ;; value. (You can always rename an autonamed bookmark later, if you ;; want to keep it and give it a meaningful name.) ;; ;; Option
bmkp-automatic-bookmark-min-distance' is the minimum
;; number of characters between automatic bookmark positions. If the
;; cursor is currently closer to some existing automatically created
;; bookmark, then no automatic bookmark is set at point. If you set
;; this to nil' then there is no limit on how close the bookmarks ;; can be. (But there is only one autonamed bookmark at any given ;; position.) ;; ;; If you want automatically created bookmarks to be temporary (not ;; saved to your bookmark file), then customize option ;;
bmkp-autotemp-bookmark-predicates' so that it includes the kind
;; of bookmarks that are set by
;; bmkp-automatic-bookmark-set-function'. For example, if automatic ;; bookmarking sets autonamed bookmarks, then ;;
bmkp-autotemp-bookmark-predicates' should include
;; bmkp-autonamed-bookmark-p' or ;;
bmkp-autonamed-this-buffer-bookmark-p' (it includes both of these
;; by default). Remember that you can toggle whether a given
;; bookmark is temporary or savable, using M-X' in the bookmark-list ;; display (buffer
Bookmark List').
;;
;; If you want the bookmarks to be automatically highlighted, then
;; customize option bmkp-auto-light-when-set' to highlight bookmarks ;; of the appropriate kind. For example, to highlight autonamed ;; bookmarks set it to
autonamed-bookmark'.
;;
;; NOTE: If you use Emacs 20, then by default
;; bmkp-automatic-bookmark-mode' is global rather than local. The ;; doc string tells you how to make it local instead. If you use ;; Emacs 21, then
bmkp-automatic-bookmark-mode' is local but there
;; is no global mode, bmkp-global-automatic-bookmark-mode'. This is ;; because Emacs 21 does not support
define-globalized-minor-mode'.
;;
;;
;;(@* "Automatic Info Bookmarking")
;; *** Automatic Info Bookmarking ***
;;
;; If you enable global minor mode bmkp-info-auto-bookmark-mode', ;; each Info node you visit is bookmarked automatically, using the ;; default bookmark name, which is the Info manual name plus the node ;; name. For example, node
Lisp Data Types' in the Elisp manual
;; gives you a bookmark named (elisp) Lisp Data Types'. ;; ;; With the mode enabled, when you visit an Info node an existing ;; bookmark with the same name is always updated. If no such ;; bookmark exists then a new one is created, provided option ;;
bmkp-info-auto-type' has value create-or-replace'. If it has ;; value
update-only' then no new bookmark is created. The default
;; option value is update-only'. You can toggle the value using ;; command
bmkp-toggle-info-auto-type'.
;;
;; With bmkp-info-auto-bookmark-mode' enabled, even if you have ;; created Info bookmarks with the default names manually, they are ;; updated automatically. In particular, updating a bookmark ;; increments the recorded number of visits to the Info node and the ;; time of the last visit. ;; ;; You can sort bookmarks in the bookmark-list display by the time of ;; last visit, using
s d', or by the number of visits, using s v'. ;; ;; This gives you an easy way to see which parts of the manuals you ;; have visited most recently and how much you have visited them. ;; Showing only Info bookmarks gives you the effect of a persistent ;; mini-manual of just the visited Info nodes. Turn the mode off ;; anytime you do not want to record Info visits. ;; ;; Also useful in this context, though not related to bookmarking, is ;; the ability to save your Info history persistently, so links to ;; visited nodes are shown using a different face. This makes it ;; easy to see which parts of a manual you have already looked at. ;; (And checking a bookmark to a visited node shows you how much you ;; have visited it.) ;; ;; If you use library
info+.el' then you have this complementary
;; ability save your Info history list persistently. Just enable
;; minor mode `Info-persist-history-mode'.
;;(@* "Highlighting Bookmark Locations") ;; ** Highlighting Bookmark Locations ** ;; ;; You can highlight the location (destination) of a bookmark. For ;; this feature you need library `bookmark+-lit.el' in addition to ;; the other Bookmark+ libraries. ;; ;; You might never want to highlight a bookmark, or you might want to ;; highlight most or even all bookmarks, or your use of highlighting ;; might fall somewhere between. It depends on what kind of ;; bookmarks you have and how you use them. Bookmark+ lets you ;; choose. By default, no bookmarks are highlighted.
;;(@* "Defining How to Highlight")
;; ** Defining How to Highlight **
;;
;; By default, autonamed bookmarks are highlighted differently from
;; non-autonamed bookmarks. Bookmark highlighting uses a style and a
;; face. The available styles are these:
;;
;; * Region - Highlight the region, if a region bookmark
;; * Line - Highlight line of the bookmark position
;; * Position - Highlight character at bookmark position
;; * Line Beginning - Highlight first character on line
;; * Left Fringe - Highlight only the left fringe
;; * Left Fringe + Line - Highlight the left fringe and the line
;; * Right Fringe - Highlight only the right fringe
;; * Right Fringe + Line - Highlight the right fringe and the line
;;
;; You can customize the default styles and faces to use for
;; autonamed and non-autonamed bookmarks. You can also customize the
;; fringe bitmaps to use.
;;
;; * bmkp-light-autonamed' (face) ;; *
bmkp-light-non-autonamed' (face)
;; * bmkp-light-autonamed-region' (face) ;; *
bmkp-light-non-autonamed-region' (face)
;; * bmkp-light-style-autonamed' (option) ;; *
bmkp-light-style-non-autonamed' (option)
;; * bmkp-light-style-autonamed-region' (option) ;; *
bmkp-light-style-non-autonamed-region' (option)
;; * bmkp-light-left-fringe-bitmap' (option) ;; *
bmkp-light-right-fringe-bitmap' (option)
;;
;; Note: A region, position, or line highlight acts more or less like
;; an Emacs marker: it moves with the surrounding text. As you edit
;; the text in the buffer, the highlighted location can thus become
;; out of sync with the recorded position. This is normal. When you
;; jump to the bookmark, its highlight is automatically repositioned
;; to the recorded location, possibly adjusted according to the
;; surrounding context.
;;
;; In addition to the default highlighting, which you can customize,
;; you can set the highlighting for individual bookmarks and
;; particular sets of bookmarks (overriding their default
;; highlighting). These individual settings are saved as part of the
;; bookmarks themselves.
;;
;; In the bookmark list display (buffer *Bookmark List*'): ;; ;; *
H +' - Set the highlighting for this line's bookmark
;; * H > +' - Set the highlighting for the marked bookmarks ;; ;; Globally, you can use
M-x bmkp-set-lighting-for-bookmark' to set
;; the highlighting for a given bookmark.
;;
;; Each of these commands prompts you (with completion) for the style
;; and face to set, as well as for a condition that controls whether
;; to highlight. Each of these is optional - just hit RET' (empty ;; input) at its prompt to skip setting it. ;; ;; The condition is an Emacs-Lisp sexp that is evaluated whenever an ;; attempt is made to highlight the bookmark. Any resulting value ;; except
:no-light' highlights the bookmark. The sexp can refer to
;; the variables this-bookmark' and
this-bookmark-name', whose
;; values are the bookmark to be highlighted and its name,
;; respectively.
;;
;; So, for example, if you wanted to be prompted each time before
;; highlighting a certain bookmark you might set its highlighting
;; condition to a sexp such as this:
;;
;; (or (y-or-n-p (format "Highlight %s' " this-bookmark-name)) ;; :no-light) ;; ;; If you hit
n' at the prompt then :no-light' is returned and the ;; bookmark is not highlighted. ;; ;; In the bookmark-list display, a pink-background, one-character ;; highlight is used next to each bookmark that has a highlight ;; override wrt the default. You can see what that override setting ;; is by using
C-u C-h RET' - look for the lighting' entry in the ;; bookmark definition. ;; ;; ;;(@* "Highlighting On Demand") ;; *** Highlighting On Demand *** ;; ;; You can highlight or unhighlight a bookmark or a set of bookmarks ;; on demand. ;; ;; In the bookmark list (buffer
Bookmark List'):
;;
;; * H H',
H U' - Highlight, unhighlight this line's bookmark
;;
;; * H > H',
H > U' - Highlight, unhighlight the marked bookmarks
;;
;; Globally:
;;
;; * C-x x C-u' - Unhighlight a highlighted bookmark at ;; point or on the same line (in that order) ;; ;; *
C-x x h', C-x x u' - Highlight, unhighlight a bookmark in the ;; current buffer (with completion). ;; ;; *
C-x x H', C-x x U' - Highlight, unhighlight bookmarks: ;; ;; With plain
C-u': all bookmarks
;;
;; With C-u C-u': navigation-list bookmarks ;; ;; Otherwise, bookmarks in current buffer: ;; No prefix arg: all bookmarks ;; Prefix arg > 0: autonamed bookmarks ;; < 0: non-autonamed bookmarks ;; ;; The default bookmark for
C-x x u' is the same bookmark that is
;; unhighlighted by C-x x C-u': a (highlighted) bookmark at point ;; (preferably) or on the same line. The latter key binding just ;; saves you having to hit
RET' to pick the default.
;;
;; When you use C-x x h', you can use a prefix argument to override ;; both the default highlighting and any highlighting that is ;; recorded for the bookmark itself. You are prompted for the style ;; or face to use: ;; ;; * Negative arg: prompted for style ;; * Non-negative arg: prompted for face ;; * Plain
C-u': prompted for style and face
;;
;;
;;(@* "Highlighting Automatically")
;; *** Highlighting Automatically ***
;;
;; You can also highlight automatically, whenever you set (create) a
;; bookmark or jump to one. This is controlled by these options:
;;
;; * bmkp-auto-light-when-set' ;; *
bmkp-auto-light-when-jump'
;;
;; You can choose any of these values for either option:
;;
;; * Autonamed bookmark
;; * Non-autonamed bookmark
;; * Any bookmark
;; * Autonamed bookmarks in buffer
;; * Non-autonamed bookmarks in buffer
;; * All bookmarks in buffer
;; * None (no automatic highlighting) - the default
;;
;; The first three values highlight only the bookmark being set or
;; jumped to.
;;
;; Be aware that, depending on the setting, highlighting can take a
;; while.
;;(@* "Using Highlighted Bookmarks")
;; ** Using Highlighted Bookmarks **
;;
;; Once you have highlighted bookmarks, what can you do with them?
;; Obviously, the highlighting can help you distinguish and find
;; bookmarks visually. But highlighting also serves as yet another
;; way to define sets: the highlighted vs unhighlighted bookmarks.
;;
;; Any command that operates on a set of bookmarks can be applied to
;; one or the other of these two sets. Bookmark+ defines only a few
;; such operations, but you can easily define others.
;;
;; In addition to such specific commands, you can also apply general
;; operations to the highlighted or unhighlighted bookmarks, using
;; the bookmark-list display (*Bookmark List*').
H S' shows only
;; the bookmarks that are currently highlighted, and H M' marks ;; them. You can then perform any of the available bookmark-list ;; operations on them. ;; ;; Globally, you can use these keys: ;; ;; *
C-x x =' - List the bookmarks that are
;; highlighted at point. With a
;; prefix arg, show the full data.
;;
;; * C-x j h',
C-x 4 j h' - Jump to a highlighted bookmark.
;; Only highlighted bookmarks are
;; completion candidates.
;;
;; * C-x x C-down',
C-x x C-up' - Cycle to the next and previous
;; highlighted bookmark.
;;(@* "Bookmark Links")
;; ** Bookmark Links **
;;
;; You can use command bmkp-insert-bookmark-link' to create links in ;; any Emacs text that jump to particular bookmarks when you follow ;; them (by hitting
RET' or clicking mouse-2'). If you hit
?' or
;; double-click mouse-1' on such a bookmark link then the bookmark ;; is described, showing the same information as
C-h M'
;; (bmkp-describe-bookmark'). ;; ;; You are prompted for the bookmark to link. If the region is ;; active and nonempty then the link is put on its text. Otherwise, ;; you are prompted for the link text, which is inserted. The ;; default link text is the bookmark name in this case. ;; ;; The bookmark linked can be of any type. ;; ;; This simple feature lets you easily create "launching pads" for ;; different sets of bookmarks: buffers or files that consist of ;; bookmark links and any other text you like. This gives you yet ;; another way to organize bookmarks (and so also the files, ;; directories, etc. that they target). ;; ;; If you also use library
font-lock+.el' then the links appear with
;; face link', even in a font-locked buffer. (Library ;;
font-lock+.el' just provides this feature of allowing
;; non-font-lock highlighting in a font-locked buffer. See
;; https://lists.gnu.org/archive/html/emacs-devel/2014-08/msg00540.html.)
;;
;; The links you create this way are not persistent, but you can of
;; course re-create them using Lisp.
;;
;;
;;(@* "Org Mode Links that Jump To Bookmarks")
;; *** Org Mode Links that Jump To Bookmarks ***
;;
;; You can also easily define Org-mode links that jump to bookmarks.
;; These links are persistent. Again, the bookmark linked can be of
;; any type.
;;
;; You can use the standard Org command org-store-link' (
C-c l') in
;; buffer *Bookmark List*' to store a link to the bookmark at point. ;; (This is also item
Store Org Link' in the mouse-3 popup menu.)
;;
;; Outside buffer *Bookmark List*' you can use command ;;
bmkp-store-org-link' to store a link to any bookmark. You are
;; prompted for the bookmark name. You can even enter the name of a
;; bookmark that does not yet exist. (This is also item Store Org ;; Link To...' on menu
Bookmarks'.)
;;
;; If you use a numeric prefix arg with either command then the
;; bookmark link stored will be for jumping to the bookmark in the
;; same window. Without a numeric prefix arg, the link will use
;; another window. (Org mode defines other behaviors for non-numeric
;; prefix args, such as C-u C-u'.) ;; ;; As usual, to insert a bookmark link, you use command ;;
org-insert-link'. Enter the name of the target bookmark at the
;; prompt. In Org mode you can use the usual Org key bindings to
;; follow the link. In any mode you can use standard Org command
;; `org-open-at-point-global' (not bound to a key by default).
;;(@* "Bookmark Menus")
;; ** Bookmark Menus **
;;
;; Two menu-bar menus for Bookmark+ have already been mentioned:
;;
;; * Menu Bookmark+', for the bookmark-list display (buffer ;;
Bookmark List').
;;
;; * Menu Bookmarks', which is typically a submenu of the menu-bar ;;
Edit' menu (available also with vanilla Emacs but enhanced by
;; Bookmark+).
;;
;; Access to bookmarks for the currently visited file or current
;; buffer is available as a Bookmarks Here' submenu of the ;; major-mode menu-bar menu in modes Info and Buffer-Menu, if option ;;
bmkp-add-bookmarks-here-menu-flag' is non-nil'. ;; ;; The menu items let you cycle among bookmarks in the current ;; file/buffer or access the bookmark-list display for only those ;; bookmarks. ;; ;; If you use library Dired+ then the same access is available in ;; Dired mode on menu-bar menu
Dir' > Bookmark' >
Here'.
;;
;; If you use library Imenu+ then the same access is available in an
;; Imenu submenu Bookmarks Here'. In this case there are also menu ;; items to jump to each bookmark in the file/buffer. For Imenu, ;; display of the menu is controlled by option ;;
imenup-show-bookmarks-flag'.
;;(@* "Use Bookmark+ with Icicles")
;; ** Use Bookmark+ with Icicles **
;;
;; Icicles' (https://www.emacswiki.org/emacs/Icicles) enhances your ;; use of Bookmark+ in several ways. ;; ;; When jumping to a bookmark, you can narrow the completion ;; candidates to bookmarks of a particular type (e.g. Info, using ;;
C-M-i'; remote, using C-M-@'; region, using
C-M-r'). You can
;; narrow again (and again), to another bookmark type, to get the
;; intersection (e.g. remote Info bookmarks that define a region).
;;
;; You can also narrow against different bookmark-name patterns
;; (e.g. regexps) - so-called "progressive completion". And take the
;; complement (e.g., bookmarks whose names do not match
;; foo.*2010.*bar'). (This is not special to bookmarks; it is ;; standard
Icicles' practice.)
;;
;; In Icicle mode, several of the Bookmark+ keys are remapped to
;; corresponding Icicles' multi-commands. A bookmark jump key thus ;; becomes a bookmarks browser. For example,
C-x j d' browses among
;; any number of Dired bookmarks.
;;
;; A single key can set a bookmark or visit bookmarks. This key is
;; whatever command bmkp-bookmark-set-confirm-overwrite' would ;; normally be bound to - e.g.
C-x r m'. A prefix arg controls what
;; it does. If negative (M--'), jump to (browse) bookmarks. ;; Otherwise, set a bookmark using ;;
bmkp-bookmark-set-confirm-overwrite', as follows:
;;
;; * No prefix arg: Prompt for the bookmark name. The candidates are
;; bookmarks in the current buffer (or all bookmarks if there are
;; none in the current buffer).
;;
;; * (Non-negative) numeric prefix arg: No prompt. Use the buffer
;; name plus the text of the region (if active) or the current line
;; as the bookmark name. Quickest way to set a bookmark.
;;
;; * Plain C-u': Prompt for name, no bookmark overwrite. ;; ;; During completion of a bookmark name, many features of the ;; bookmark-list display (see (@> "The Bookmark List Display")) are ;; available on the fly. Buffer
Completions' acts like a dynamic
;; version of *Bookmark List*': ;; ;; * Candidates are highlighted in the
Completions' window
;; according to their bookmark type.
;;
;; * Candidates are Icicles' multi-completions with up to three ;; parts: ;; ;; a. the bookmark name ;; b. the bookmark file or buffer name ;; c. any tags ;; ;; You can match any or all of the parts. For example, you can ;; match bookmarks that have tags by typing this regexp: ;; ;; C-M-j . * C-M-j S-TAB ;; ;; Each
C-M-j' inserts ^G\n', which is
icicle-list-join-string',
;; the string used to join the parts. This regexp says, "match the
;; completion candidates that have all three parts (two join
;; strings)", hence some tags.
;;
;; You can turn off the use of multi-completion candidates for
;; subsequent commands, so only bookmark names are used, by hitting
;; M-m' in the minibuffer. You can think of this as similar to ;; using
M-t' in *Bookmark List*' to toggle showing file names. ;; You can make not showing files and tags the default behavior by ;; customizing
icicle-show-multi-completion-flag'.
;;
;; * You can sort completion candidates using the Bookmark+ sort
;; orders. Use C-,' to cycle among sort orders. ;; ;; * You can use
Icicles' candidate-help keys (C-M-RET', ;;
C-M-down', etc.) to get detailed information about the current
;; bookmark candidate. C-u C-M-RET' shows the complete, internal ;; info defining the bookmark. And without doing anything, summary ;; info about the current candidate is available in the mode line ;; of buffer
Completions'.
;;
;; * You can use Icicles' candidate-action keys (
C-RET',
;; C-mouse-2',
C-down', etc.) to visit any number of bookmarks.
;; For example, holding down C-down' cycles among the current ;; bookmark candidates, opening each in turn. ;; ;; * You can use
S-delete' to delete the bookmark named by the
;; current candidate. You can delete any number of bookmarks this
;; way, during a single invocation of a bookmark command.
;;
;; * You can define Icicles' sets of bookmarks, persistent or not, ;; and act on their members in various ways. ;; ;; During file-name completion, you can do any of the following on ;; the fly: ;; ;; * Jump to one or more file bookmarks, using
C-x m'.
;;
;; * Create one or more autofile bookmarks, using C-x a a'. ;; ;; * Add tags to one or more files or directories (autofile ;; bookmarks), using
C-x a +'.
;;
;; * Remove tags from one or more files or directories (autofile
;; bookmarks), using C-x a -'. ;; ;; There are 25 Icicles commands for searching bookmark destinations! ;; The most general is
icicle-search-bookmark'. Others let you
;; search specific kinds of bookmarks, or bookmarks having various
;; combinations of tags.
;;
;; During Icicles search (of anything, not just a bookmark
;; destination), you can save sets of completion candidates, which
;; means sets of search hits, as bookmarks. And Icicles lets you use
;; set operations (complement, union, intersection, difference etc.)
;; on the current set of search hits.
;;
;; When you "jump" to an Icicles search-hits bookmark, its recorded
;; search hits are restored to Icicles search as completion
;; candidates, either replacing the current candidates or adding to
;; them.
;;
;; You can thus save and later return to different sets of search
;; results using different bookmarks. You can "jump" to an Icicles
;; search-hits bookmark during any Icicles search, whether you search
;; a file, a buffer, multiple files, or multiple buffers.
;;(@* "Bookmark Compatibility with Vanilla Emacs (bookmark.el')") ;; ** Bookmark Compatibility with Vanilla Emacs (
bookmark.el') **
;;
;; Bookmark+ is generally compatible with GNU Emacs versions 20 and
;; later. You can use bookmarks with Bookmark+ regardless of whether
;; they were created using Bookmark+ or vanilla Emacs (i.e., library
;; bookmark.el'). ;; ;; But for best results, if you have bookmarks that you created using ;; Bookmark+ then use Bookmark+, not vanilla Emacs, to access them. ;; This section provides details. ;; ;; Set user option
bmkp-propertize-bookmark-names-flag', depending
;; on your usage scenario (the default is t' for Emacs 21 and later, ;;
nil' for Emacs 20):
;;
;; 1. Set it to nil' if you will often be going back and forth ;; between using Bookmark+ and using vanilla Emacs. (Do this also ;; if you use Emacs 20.) ;; ;; 2. Set it to non-
nil' if you instead always use only Bookmark+
;; (with Emacs 21 or later), or you use vanilla Emacs only to jump
;; to bookmarks but never to update or create bookmarks.
;;
;; #1 is VERY IMPORTANT. You can lose data if you do not respect it.
;;
;; The reason for rule #1 is this: When the option is non-nil' ;; Bookmark+ writes bookmarks to your bookmark file in a format that ;; can be read and used by vanilla Emacs (21 and later) but which ;; vanilla Emacs then saves as unreadable. If the option value is ;;
nil' there is no such problem.
;;
;; #2 is not a requirement. It is just a good idea, to be able to
;; take better advantage of Bookmark+. If you set the option to
;; nil' then you cannot use multiple bookmarks that have the same ;; name. Vanilla Emacs does not make good use of such critters, but ;; Bookmark+ does. Having multiple bookmarks with the same name is ;; particularly useful for autofiles. It means you can have ;; different autofiles in different directories but with the same ;; name. See (@> "Autofile Bookmarks"). ;; ;; Here is what happens when
bmkp-propertize-bookmark-names-flag' is
;; non-nil:
;;
;; Besides its name, which is what you see and use most of the time,
;; a bookmark contains other information such as the target location,
;; textual context hints, and last access time. Non-nil' ;;
bmkp-propertize-bookmark-names-flag' has no effect on vanilla
;; Emacs, but it causes Bookmark+ to put the full bookmark
;; information on the bookmark name as a text property.
;;
;; The name thus encapsulates all of the information contained in the
;; full bookmark of which it is part. Knowing the name is then
;; enough to know everything about the bookmark. Part of the
;; bookmark (its name) refers to the whole of it. In Lisp this
;; self-reference is implemented using circular structures.
;;
;; When Bookmark+ saves such circular structures to your bookmark
;; file, if the option is non-nil' then it takes care to do so in ;; such a way that they can be read in again when your bookmark file ;; is loaded. In Lisp terms, it binds
print-circle' to non-nil' ;; when it writes your bookmarks. If the option value is
nil' then
;; the circularity (self-reference) is removed before your bookmarks
;; are saved. Either way, the file is readable.
;;
;; Vanilla Emacs (21 and later) has no problem reading your bookmark
;; file if it contains such circular structures. But if you then use
;; it to save the file again, the Lisp code it writes has invalid
;; Lisp read' syntax (because it does not remove the circularity but ;; it also does not bind
print-circle' to non-nil'). ;; ;; If that happens, the result is a bookmark file that is UNREADABLE. ;; It cannot be loaded into either vanilla Emacs or Bookmark+. If ;; you do not have an uncorrupted backup version of the file to ;; revert to, then you will need to edit it by hand to clean it up. ;; ;; So do not let that happen to you! For best results use only ;; Bookmark+ to access bookmarks created using Bookmark+. ;; ;; If you must use vanilla Emacs with your bookmarks, then make sure ;; they are not saved by Bookmark+ with the option non-
nil': Using
;; Bookmark+, set the option to nil' and then save the file. ;; ;; That is: ;; ;; 1.
M-x set-variable bmkp-propertize-bookmark-names-flag nil',
;; to stop using propertized bookmark names.
;; 2. C-x x e' or
C-x r l', to display the bookmark list.
;; 3. g', to refresh the display. ;; 4.
S', to save the bookmark list.
;; 5. M-x bmkp-save-menu-list-state', to save the display state. ;; ;; Then you can use your bookmark file with vanilla Emacs (but ;; without the possibility of having multiple bookmarks with the same ;; name). ;; ;; Note that when the option value is non-
nil', propertized bookmark
;; names are saved not only to your bookmark file but also to any
;; full snapshots you create of the bookmark-list display state using
;; command bmkp-bmenu-define-full-snapshot-command' (
C-c C-C', aka
;; `C-c C-S-c'). See (@> "State-Restoring Commands and Bookmarks").
;;(@* "New Bookmark Structure")
;; ** New Bookmark Structure **
;;
;; The bookmark data structure, variable bookmark-alist', has been ;; enhanced to support new bookmark types. For a description of this ;; enhanced structure, use
C-h v bookmark-alist'.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program; see the file COPYING. If not, write to
;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
;; Floor, Boston, MA 02110-1301, USA.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Code:
;; You need not load this file. It contains only documentation.
(provide 'bookmark+-doc)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; bookmark+-doc.el ends here