;; Author: Karl Fogel <kfogel@cyclic.com>
;; Maintainer: Karl Fogel <kfogel@cyclic.com>
;; Created: July, 1993
-;; Author's Update Number: 2.6.10
+;; Author's Update Number: 2.6.13
;; Keywords: bookmarks, placeholders, annotations
;;; Summary:
;; This package is for setting "bookmarks" in files. A bookmark
;; associates a string with a location in a certain file. Thus, you
;; can navigate your way to that location by providing the string.
+;; See the "User Variables" section for customizations.
;;; Copyright info:
;; This file is part of GNU Emacs.
;; Based on info-bookmark.el, by Karl Fogel and Ken Olstad
;; <olstad@msc.edu>.
+;; Thanks to Mikio Nakajima <PBC01764@niftyserve.or.jp> for many bugs
+;; reported and fixed.
+
;; Enough with the credits already, get on to the good stuff:
;; FAVORITE CHINESE RESTAURANT:
;; the list will be presented in the order it is recorded
;; (chronologically), which is actually fairly useful as well.
-;;; Code:
+;;; User Variables
+
+(defvar bookmark-use-annotations nil
+ "*If non-nil, saving a bookmark will query for an annotation in a
+buffer.")
+
+
+(defvar bookmark-save-flag t
+ "*Controls when Emacs saves bookmarks to a file.
+--> Nil means never save bookmarks, except when `bookmark-save' is
+ explicitly called \(\\[bookmark-save]\).
+--> t means save bookmarks when Emacs is killed.
+--> Otherise, it should be a number that is the frequency with which
+ the bookmark list is saved \(i.e.: the number of times which
+ Emacs' bookmark list may be modified before it is automatically
+ saved.\). If it is a number, Emacs will also automatically save
+ bookmarks when it is killed.
+
+Therefore, the way to get it to save every time you make or delete a
+bookmark is to set this variable to 1 \(or 0, which produces the same
+behavior.\)
+
+To specify the file in which to save them, modify the variable
+bookmark-default-file, which is `~/.emacs.bmk' by default.")
+
+
+(defconst bookmark-old-default-file "~/.emacs-bkmrks"
+ "*The .emacs.bmk file used to be called this.")
+
+
+;; defvarred to avoid a compilation warning:
+(defvar bookmark-file nil
+ "Old name for `bookmark-default-file'.")
+
+(defvar bookmark-default-file
+ (if bookmark-file
+ ;; In case user set `bookmark-file' in her .emacs:
+ bookmark-file
+ (if (eq system-type 'ms-dos)
+ "~/emacs.bmk" ; Cannot have initial dot [Yuck!]
+ "~/.emacs.bmk"))
+ "*File in which to save bookmarks by default.")
+
+
+(defvar bookmark-version-control 'nospecial
+ "*Whether or not to make numbered backups of the bookmark file.
+It can have four values: t, nil, `never', and `nospecial'.
+The first three have the same meaning that they do for the
+variable `version-control', and the final value `nospecial' means just
+use the value of `version-control'.")
+
+
+(defvar bookmark-completion-ignore-case t
+ "*Non-nil means bookmark functions ignore case in completion.")
+
+
+(defvar bookmark-sort-flag t
+ "*Non-nil means that bookmarks will be displayed sorted by bookmark
+name. Otherwise they will be displayed in LIFO order (that is, most
+recently set ones come first, oldest ones come last).")
+
+
+(defvar bookmark-automatically-show-annotations t
+ "*Nil means don't show annotations when jumping to a bookmark.")
+
+
+(defvar bookmark-bmenu-file-column 30
+ "*Column at which to display filenames in a buffer listing bookmarks.
+You can toggle whether files are shown with \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-toggle-filenames].")
+
+
+(defvar bookmark-bmenu-toggle-filenames t
+ "*Non-nil means show filenames when listing bookmarks.
+This may result in truncated bookmark names. To disable this, put the
+following in your .emacs:
+
+\(setq bookmark-bmenu-toggle-filenames nil\)")
+
+
+(defvar bookmark-menu-length 70
+ "*Maximum length of a bookmark name displayed on a popup menu.")
+
+
+;;; No user-serviceable parts beyond this point.
;; Added for lucid emacs compatibility, db
(or (fboundp 'defalias) (fset 'defalias 'fset))
;; suggested for lucid compatibility by david hughes:
-(or (fboundp 'frame-height) (fset 'frame-height 'screen-height))
+(or (fboundp 'frame-height) (defalias 'frame-height 'screen-height))
\f
key of your choice to `bookmark-map'. All interactive bookmark
functions have a binding in this keymap.")
-(defvar bookmark-use-annotations nil
- "*If non-nil, saving a bookmark will query for an annotation in a
-buffer.")
-
;;;###autoload
(define-prefix-command 'bookmark-map)
(defvar bookmark-alist ()
"Association list of bookmarks and their records.
You probably don't want to change the value of this alist yourself;
-instead, let the various bookmark functions do it for you.")
+instead, let the various bookmark functions do it for you.
+
+The format of the alist is
+
+ \(BOOKMARK1 BOOKMARK2 ...\)
+
+where each BOOKMARK is of the form
+
+\(NAME
+ \(filename . FILE\)
+ \(front-context-string . FRONT-STR\)
+ \(rear-context-string . REAR-STR\)
+ \(position . POS\)
+ \(info-node . POS\)
+ \(annotation . ANNOTATION\)\)
+
+So the cdr of each bookmark is an alist too.
+`info-node' is optional, by the way.")
(defvar bookmarks-already-loaded nil)
(make-variable-buffer-local 'bookmark-current-bookmark)
-(defvar bookmark-save-flag t
- "*Controls when Emacs saves bookmarks to a file.
---> Nil means never save bookmarks, except when `bookmark-save' is
- explicitly called \(\\[bookmark-save]\).
---> t means save bookmarks when Emacs is killed.
---> Otherise, it should be a number that is the frequency with which
- the bookmark list is saved \(i.e.: the number of times which
- Emacs' bookmark list may be modified before it is automatically
- saved.\). If it is a number, Emacs will also automatically save
- bookmarks when it is killed.
-
-Therefore, the way to get it to save every time you make or delete a
-bookmark is to set this variable to 1 \(or 0, which produces the same
-behavior.\)
-
-To specify the file in which to save them, modify the variable
-bookmark-default-file, which is `~/.emacs.bmk' by default.")
-
-
(defvar bookmark-alist-modification-count 0
"Number of modifications to bookmark list since it was last saved.")
-(defconst bookmark-old-default-file "~/.emacs-bkmrks"
- "*The .emacs.bmk file used to be called this.")
-
-
-;; defvarred to avoid a compilation warning:
-(defvar bookmark-file nil
- "Old name for `bookmark-default-file'.")
-
-(defvar bookmark-default-file
- (if bookmark-file
- ;; In case user set `bookmark-file' in her .emacs:
- bookmark-file
- (if (eq system-type 'ms-dos)
- "~/emacs.bmk" ; Cannot have initial dot [Yuck!]
- "~/.emacs.bmk"))
- "*File in which to save bookmarks by default.")
-
-
-(defvar bookmark-version-control 'nospecial
- "This variable controls whether or not to make numbered backups of
-the master bookmark file. It can have four values: t, nil, never, and
-nospecial. The first three have the same meaning that they do for the
-variable version-control, and the final value nospecial means just use
-the value of version-control.")
-
-
-(defvar bookmark-completion-ignore-case t
- "*Non-nil means bookmark functions ignore case in completion.")
-
-
-(defvar bookmark-sort-flag t
- "*Non-nil means that bookmarks will be displayed sorted by bookmark
-name. Otherwise they will be displayed in LIFO order (that is, most
-recently set ones come first, oldest ones come last).")
-
-
-(defvar bookmark-automatically-show-annotations t
- "*Nil means don't show annotations when jumping to a bookmark.")
-
-
(defvar bookmark-search-size 16
"Length of the context strings recorded on either side of a bookmark.")
;; Everyone else should go through them.
(defun bookmark-name-from-full-record (full-record)
- "Return name of BOOKMARK \(an alist element instead of a string\)."
+ "Return name of FULL-RECORD \(an alist element instead of a string\)."
(car full-record))
(defun bookmark-set-annotation (bookmark ann)
- "Set the annotation of BOOKMARK."
+ "Set the annotation of BOOKMARK to ANN."
(let ((cell (assq 'annotation (bookmark-get-bookmark-record bookmark))))
(if cell
(setcdr cell ann)
(defun bookmark-get-info-node (bookmark)
+ "Get the info node associated with BOOKMARK."
(cdr (assq 'info-node (bookmark-get-bookmark-record bookmark))))
(setq bookmark-history (cons (, string) bookmark-history)))))
-(defun bookmark-make (str &optional annotation overwrite)
+(defun bookmark-make (name &optional annotation overwrite)
"Make a bookmark named NAME.
Optional second arg ANNOTATION gives it an annotation.
Optional third arg OVERWRITE means replace any existing bookmarks with
this name."
(bookmark-maybe-load-default-file)
- (if (and (bookmark-get-bookmark str) (not overwrite))
+ (if (and (bookmark-get-bookmark name) (not overwrite))
;; already existing boookmark under that name and
;; no prefix arg means just overwrite old bookmark
- (setcdr (bookmark-get-bookmark str)
+ (setcdr (bookmark-get-bookmark name)
(list (bookmark-make-cell annotation)))
;; otherwise just cons it onto the front (either the bookmark
(setq bookmark-alist
(cons
- (list str
+ (list name
(bookmark-make-cell annotation))
bookmark-alist)))
;; Added by db
- (setq bookmark-current-bookmark str)
+ (setq bookmark-current-bookmark name)
(setq bookmark-alist-modification-count
(1+ bookmark-alist-modification-count))
(if (bookmark-time-to-save-p)
(defun bookmark-make-cell (annotation)
- "Return the record part of a bookmark.
+ "Return the record part of a new bookmark, given ANNOTATION.
Must be at the correct position in the buffer in which the bookmark is
-being set. This will change soon.
-Takes ANNOTATION as an argument."
+being set. This will change soon."
(` ((filename . (, (bookmark-buffer-file-name)))
(front-context-string
. (, (if (>= (- (point-max) (point)) bookmark-search-size)
(defun bookmark-upgrade-version-0-alist (old-list)
- "Upgrade a version 0 alist to the current version."
+ "Upgrade a version 0 alist OLD-LIST to the current version."
(mapcar
(lambda (bookmark)
(let* ((name (car bookmark))
;;; Core code:
;;;###autoload
-(defun bookmark-set (&optional parg)
- "Set a bookmark named NAME inside a file.
+(defun bookmark-set (&optional name parg)
+ "Set a bookmark named NAME inside a file.
+If name is nil, then the user will be prompted.
With prefix arg, will not overwrite a bookmark that has the same name
as NAME if such a bookmark already exists, but instead will \"push\"
the new bookmark onto the bookmark alist. Thus the most recently set
Use \\[bookmark-delete] to remove bookmarks \(you give it a name,
and it removes only the first instance of a bookmark with that name from
the list of bookmarks.\)"
- (interactive "P")
+ (interactive (list nil current-prefix-arg))
(or
(bookmark-buffer-file-name)
(error "Buffer not visiting a file or directory."))
(let* ((default (or bookmark-current-bookmark
(bookmark-buffer-name)))
(str
- (read-from-minibuffer
- (format "Set bookmark (%s): " default)
- nil
- (let ((now-map (copy-keymap minibuffer-local-map)))
- (progn (define-key now-map "\C-w"
- 'bookmark-yank-word)
- (define-key now-map "\C-u"
- 'bookmark-insert-current-bookmark))
- now-map)))
+ (or name
+ (read-from-minibuffer
+ (format "Set bookmark (%s): " default)
+ nil
+ (let ((now-map (copy-keymap minibuffer-local-map)))
+ (progn (define-key now-map "\C-w"
+ 'bookmark-yank-word)
+ (define-key now-map "\C-u"
+ 'bookmark-insert-current-bookmark))
+ now-map))))
(annotation nil))
(and (string-equal str "") (setq str default))
;; Ask for an annotation buffer for this bookmark
(defun bookmark-read-annotation-mode (buf point parg bookmark)
"Mode for composing annotations for a bookmark.
+Wants BUF POINT PARG and BOOKMARK.
When you have finished composing, type \\[bookmark-send-annotation] to send
the annotation.
(defun bookmark-insert-current-bookmark ()
- ;; insert this buffer's value of bookmark-current-bookmark, default
- ;; to file name if it's nil.
+ "Insert this buffer's value of bookmark-current-bookmark, default
+to file name if it's nil."
(interactive)
(let ((str
(save-excursion
(defun bookmark-insert-buffer-name ()
- ;; insert the name (sans path) of the current file into the bookmark
- ;; name that is being set.
+ "Insert the name (sans path) of the current file into the bookmark
+name that is being set."
(interactive)
(let ((str
(save-excursion
;;;###autoload
-(defun bookmark-jump (str)
+(defun bookmark-jump (bookmark)
"Jump to bookmark BOOKMARK (a point in some file).
You may have a problem using this function if the value of variable
`bookmark-alist' is nil. If that happens, you need to load in some
of the old one in the permanent bookmark record."
(interactive
(bookmark-completing-read "Jump to bookmark" bookmark-current-bookmark))
- (bookmark-maybe-historicize-string str)
- (let ((cell (bookmark-jump-noselect str)))
+ (bookmark-maybe-historicize-string bookmark)
+ (let ((cell (bookmark-jump-noselect bookmark)))
(and cell
(switch-to-buffer (car cell))
(goto-char (cdr cell))
(if bookmark-automatically-show-annotations
;; if there is an annotation for this bookmark,
;; show it in a buffer.
- (bookmark-show-annotation str)))))
+ (bookmark-show-annotation bookmark)))))
(defun bookmark-jump-noselect (str)
;;;###autoload
-(defun bookmark-relocate (str)
+(defun bookmark-relocate (bookmark)
"Relocate BOOKMARK -- prompts for a filename, and makes an already
existing bookmark point to that file, instead of the one it used to
point at. Useful when a file has been renamed after a bookmark was
set in it."
(interactive (bookmark-completing-read "Bookmark to relocate"))
- (bookmark-maybe-historicize-string str)
+ (bookmark-maybe-historicize-string bookmark)
(bookmark-maybe-load-default-file)
- (let* ((bmrk-filename (bookmark-get-filename str))
+ (let* ((bmrk-filename (bookmark-get-filename bookmark))
(newloc (expand-file-name
(read-file-name
- (format "Relocate %s to: " str)
+ (format "Relocate %s to: " bookmark)
(file-name-directory bmrk-filename)))))
- (bookmark-set-filename str newloc)))
+ (bookmark-set-filename bookmark newloc)))
;;;###autoload
-(defun bookmark-insert-location (str &optional no-history)
+(defun bookmark-insert-location (bookmark &optional no-history)
"Insert the name of the file associated with BOOKMARK.
Optional second arg NO-HISTORY means don't record this in the
minibuffer history list `bookmark-history'."
(interactive (bookmark-completing-read "Insert bookmark location"))
- (or no-history (bookmark-maybe-historicize-string str))
- (insert (bookmark-location str)))
+ (or no-history (bookmark-maybe-historicize-string bookmark))
+ (insert (bookmark-location bookmark)))
-(defun bookmark-location (str)
+(defun bookmark-location (bookmark)
"Return the name of the file associated with BOOKMARK."
(bookmark-maybe-load-default-file)
- (bookmark-get-filename str))
+ (bookmark-get-filename bookmark))
;;;###autoload
(defun bookmark-rename (old &optional new)
- "Change the name of OLD-BOOKMARK to NEWNAME.
-If called from keyboard, prompts for OLD-BOOKMARK and NEWNAME.
-If called from menubar, OLD-BOOKMARK is selected from a menu, and
-prompts for NEWNAME.
-If called from Lisp, prompts for NEWNAME if only OLD-BOOKMARK was
-passed as an argument. If called with two strings, then no prompting
-is done. You must pass at least OLD-BOOKMARK when calling from Lisp.
+ "Change the name of OLD bookmark to NEW name. If called from
+keyboard, prompts for OLD and NEW. If called from menubar, OLD is
+selected from a menu, and prompts for NEW.
+
+If called from Lisp, prompts for NEW if only OLD was passed as an
+argument. If called with two strings, then no prompting is done. You
+must pass at least OLD when calling from Lisp.
While you are entering the new name, consecutive C-w's insert
consectutive words from the text of the buffer into the new bookmark
;;;###autoload
-(defun bookmark-insert (str)
+(defun bookmark-insert (bookmark)
"Insert the text of the file pointed to by bookmark BOOKMARK.
You may have a problem using this function if the value of variable
`bookmark-alist' is nil. If that happens, you need to load in some
bookmarks. See help on function `bookmark-load' for more about
this."
(interactive (bookmark-completing-read "Insert bookmark contents"))
- (bookmark-maybe-historicize-string str)
+ (bookmark-maybe-historicize-string bookmark)
(bookmark-maybe-load-default-file)
(let ((orig-point (point))
(str-to-insert
(save-excursion
- (set-buffer (car (bookmark-jump-noselect str)))
+ (set-buffer (car (bookmark-jump-noselect bookmark)))
(buffer-substring (point-min) (point-max)))))
(insert str-to-insert)
(push-mark)
(defun bookmark-save (&optional parg file)
"Save currently defined bookmarks.
Saves by default in the file defined by the variable
-`bookmark-default-file'. With a prefix arg, save it in file FILE.
+`bookmark-default-file'. With a prefix arg, save it in file FILE
+\(second argument\).
If you are calling this from Lisp, the two arguments are PREFIX-ARG
and FILE, and if you just want it to write to the default file, then
(defvar bookmark-bmenu-hidden-bookmarks ())
-(defvar bookmark-bmenu-file-column 30
- "*Column at which to display filenames in a buffer listing bookmarks.
-You can toggle whether files are shown with \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-toggle-filenames].")
-
-
-(defvar bookmark-bmenu-toggle-filenames t
- "*Non-nil means show filenames when listing bookmarks.
-This may result in truncated bookmark names. To disable this, put the
-following in your .emacs:
-
-\(setq bookmark-bmenu-toggle-filenames nil\)")
-
-
(defvar bookmark-bmenu-mode-map nil)
(run-hooks 'bookmark-bmenu-mode-hook))
-(defun bookmark-bmenu-toggle-filenames (&optional parg)
+(defun bookmark-bmenu-toggle-filenames (&optional show)
"Toggle whether filenames are shown in the bookmark list.
Optional argument SHOW means show them unconditionally."
(interactive)
(cond
- (parg
+ (show
(setq bookmark-bmenu-toggle-filenames nil)
(bookmark-bmenu-show-filenames)
(setq bookmark-bmenu-toggle-filenames t))
(delete-char -1)
(insert ?\ ))
(or (string-equal tem bmrk)
- (memq tem others)
+ (member tem others)
(setq others (cons tem others))))
(setq others (nreverse others)
tem (/ (1- (frame-height)) (1+ (length others))))
(delete-other-windows)
(bookmark-jump bmrk)
(bury-buffer menu)
- (if (equal (length others) 0)
- nil
- (while others
- (split-window nil tem)
- (other-window 1)
- (bookmark-jump (car others))
- (setq others (cdr others)))
+ (if others
+ (while others
+ (split-window nil tem)
+ (other-window 1)
+ (bookmark-jump (car others))
+ (setq others (cdr others)))
(other-window 1)))))
(defun bookmark-bmenu-unmark (&optional backup)
"Cancel all requested operations on bookmark on this line and move down.
-Optional ARG means move up."
+Optional BACKUP means move up."
(interactive "P")
(beginning-of-line)
(if (bookmark-bmenu-check-position)
\f
;;; Menu bar stuff. Prefix is "bookmark-menu".
-(defvar bookmark-menu-length 70
- "*Maximum length of a bookmark name displayed on a popup menu.")
-
-
(defun bookmark-menu-build-paned-menu (name entries)
"Build a multi-paned menu named NAME from the strings in ENTRIES.
That is, ENTRIES is a list of strings which appear as the choices
You may have a problem using this function if the value of variable
`bookmark-alist' is nil. If that happens, you need to load in some
bookmarks. See help on function `bookmark-load' for more about
-this."
+this.
+
+Warning: this function only takes an EVENT as argument. Use the
+corresponding bookmark function from Lisp \(the one without the
+\"-menu-\" in its name\)."
(interactive "e")
(bookmark-popup-menu-and-apply-function
'bookmark-insert "Insert Bookmark Contents" event))
You may have a problem using this function if the value of variable
`bookmark-alist' is nil. If that happens, you need to load in some
bookmarks. See help on function `bookmark-load' for more about
-this."
+this.
+
+Warning: this function only takes an EVENT as argument. Use the
+corresponding bookmark function from Lisp \(the one without the
+\"-menu-\" in its name\)."
(interactive "e")
(bookmark-popup-menu-and-apply-function
'bookmark-jump "Jump to Bookmark" event))
;;;###autoload
(defun bookmark-menu-locate (event)
"Insert the name of the file associated with BOOKMARK.
-\(This is not the same as the contents of that file\)."
+\(This is not the same as the contents of that file\).
+
+Warning: this function only takes an EVENT as argument. Use the
+corresponding bookmark function from Lisp \(the one without the
+\"-menu-\" in its name\)."
(interactive "e")
(bookmark-popup-menu-and-apply-function
'bookmark-insert-location "Insert Bookmark Location" event))
While you are entering the new name, consecutive C-w's insert
consectutive words from the text of the buffer into the new bookmark
-name."
+name.
+
+Warning: this function only takes an EVENT as argument. Use the
+corresponding bookmark function from Lisp \(the one without the
+\"-menu-\" in its name\)."
(interactive "e")
(bookmark-popup-menu-and-apply-function
'bookmark-rename "Rename Bookmark" event))
Removes only the first instance of a bookmark with that name. If
there are one or more other bookmarks with the same name, they will
not be deleted. Defaults to the \"current\" bookmark \(that is, the
-one most recently used in this file, if any\)."
+one most recently used in this file, if any\).
+
+Warning: this function only takes an EVENT as argument. Use the
+corresponding bookmark function from Lisp \(the one without the
+\"-menu-\" in its name\)."
(interactive "e")
(bookmark-popup-menu-and-apply-function
'bookmark-delete "Delete Bookmark" event))
(defvar menu-bar-bookmark-map (make-sparse-keymap "Bookmark functions"))
;;;###autoload
-(fset 'menu-bar-bookmark-map (symbol-value 'menu-bar-bookmark-map))
+(defalias 'menu-bar-bookmark-map (symbol-value 'menu-bar-bookmark-map))
;;;###autoload
(define-key menu-bar-bookmark-map [load]
projects / emacs.git / commitdiff