From 4eadcdf806c1a7487ca165ea954af5b1c4854f13 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Sun, 18 Jun 1995 22:46:02 +0000 Subject: [PATCH] Make doc strings and argument names consistent where necessary. Moved user variables to own section. (bookmark-alist): Better doc string. (bookmark-insert-current-bookmark): Doc string. (bookmark-insert-buffer-name): Doc string. (bookmark-set): Take optional NAME argument. (bookmark-bmenu-select): Use member to test for string's presence. Use a more efficent test at end, as suggested by Mikio Nakajima. --- lisp/bookmark.el | 353 +++++++++++++++++++++++++++-------------------- 1 file changed, 200 insertions(+), 153 deletions(-) diff --git a/lisp/bookmark.el b/lisp/bookmark.el index 6c6902ebe65..2fbd68fc337 100644 --- a/lisp/bookmark.el +++ b/lisp/bookmark.el @@ -5,13 +5,14 @@ ;; Author: Karl Fogel ;; Maintainer: Karl Fogel ;; 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. @@ -65,6 +66,9 @@ ;; Based on info-bookmark.el, by Karl Fogel and Ken Olstad ;; . +;; Thanks to Mikio Nakajima for many bugs +;; reported and fixed. + ;; Enough with the credits already, get on to the good stuff: ;; FAVORITE CHINESE RESTAURANT: @@ -87,13 +91,96 @@ ;; 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-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)) @@ -120,10 +207,6 @@ so that you have a bookmark prefix, just use `global-set-key' and bind a 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) @@ -167,7 +250,24 @@ buffer.") (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) @@ -193,69 +293,10 @@ through a file easier.") (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.") @@ -273,7 +314,7 @@ recently set ones come first, oldest ones come last).") ;; 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)) @@ -308,7 +349,7 @@ That is, all information but the name." (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) @@ -375,6 +416,7 @@ That is, all information but the name." (defun bookmark-get-info-node (bookmark) + "Get the info node associated with BOOKMARK." (cdr (assq 'info-node (bookmark-get-bookmark-record bookmark)))) @@ -425,16 +467,16 @@ menus, so `completing-read' never gets a chance to set `bookmark-history'." (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 @@ -443,12 +485,12 @@ this name." (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) @@ -456,10 +498,9 @@ this name." (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) @@ -565,7 +606,7 @@ affect point." (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)) @@ -647,8 +688,9 @@ This expects to be called from point-min in a bookmark file." ;;; 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 @@ -668,7 +710,7 @@ name of the file being visited. 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.")) @@ -682,15 +724,16 @@ the list of bookmarks.\)" (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 @@ -773,6 +816,7 @@ as a string, as an arg.") (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. @@ -861,8 +905,8 @@ as the new annotation for a bookmark." (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 @@ -872,8 +916,8 @@ as the new annotation for a bookmark." (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 @@ -966,7 +1010,7 @@ For example, if this is a Info buffer, return the Info file's name." ;;;###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 @@ -979,15 +1023,15 @@ will then jump to the new location, as well as recording it in place 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) @@ -1058,47 +1102,47 @@ of the old one in the permanent bookmark record." ;;;###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 @@ -1131,19 +1175,19 @@ name." ;;;###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) @@ -1209,7 +1253,8 @@ instead." (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 @@ -1328,19 +1373,6 @@ explicitly." (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-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) @@ -1482,12 +1514,12 @@ Bookmark names preceeded by a \"*\" have annotations. (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)) @@ -1656,20 +1688,19 @@ You can mark bookmarks with the \\\\[bookmark-bmenu-mar (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))))) @@ -1791,7 +1822,7 @@ The current window remains selected." (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) @@ -1895,10 +1926,6 @@ and then move up one line" ;;; 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 @@ -1967,7 +1994,11 @@ The number of panes depends on the number of bookmarks." 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)) @@ -1979,7 +2010,11 @@ this." 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)) @@ -1988,7 +2023,11 @@ this." ;;;###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)) @@ -2006,7 +2045,11 @@ is done. You must pass at least OLD-BOOKMARK 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 -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)) @@ -2018,7 +2061,11 @@ name." 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)) @@ -2034,7 +2081,7 @@ one most recently used in this file, if any\)." (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] -- 2.39.2