diff options
Diffstat (limited to 'lisp/bookmark.el')
| -rw-r--r-- | lisp/bookmark.el | 195 |
1 files changed, 113 insertions, 82 deletions
diff --git a/lisp/bookmark.el b/lisp/bookmark.el index 5d8f252a4fc..095a4491ead 100644 --- a/lisp/bookmark.el +++ b/lisp/bookmark.el @@ -82,10 +82,11 @@ ;; define the map, so it can be bound by those who desire to do so: -(defvar bookmark-map nil "This is a keymap containing bookmark -functions. It is not bound to any key by default: to bind it 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 +(defvar bookmark-map nil + "Keymap containing bindings to bookmark functions. +It is not bound to any key by default: to bind it +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.") (define-prefix-command 'bookmark-map) @@ -96,7 +97,7 @@ functions have a binding in this keymap.") (define-key bookmark-map "j" 'bookmark-jump) (define-key bookmark-map "i" 'bookmark-insert) (define-key bookmark-map "f" 'bookmark-locate) ; "f" for "find" -(define-key bookmark-map "n" 'bookmark-rename) ; "n" for "new name" +(define-key bookmark-map "r" 'bookmark-rename) ;; deletes bookmarks (define-key bookmark-map "d" 'bookmark-delete) ;; loads new file @@ -118,47 +119,41 @@ functions have a binding in this keymap.") ;; more stuff added by db. (defvar bookmark-current-bookmark nil - "This variable stores the bookmark most recently set, jumped to, or -renamed. It is buffer local, used to make moving a bookmark forward + "Name of bookmark most recently used in the current file. +It is buffer local, used to make moving a bookmark forward through a file easier.") (make-variable-buffer-local 'bookmark-current-bookmark) (defvar bookmark-save-flag t - "*This variable determines when Emacs\' internal bookmark list will -be saved 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. + "*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-file, which is \`~/.emacs-bkmrks\' by default.") +bookmark-file, which is `~/.emacs-bkmrks' by default.") (defvar bookmark-alist-modification-count 0 - "Number of times the bookmark list has been modified since last -saved.") + "Number of modifications to bookmark list since it was last saved.") (defvar bookmark-file "~/.emacs-bkmrks" "*File in which to save bookmarks by default.") (defvar bookmark-completion-ignore-case t - "*Non-nil means those bookmark functions which use completion will -be case-insensitive in completion.") + "*Non-nil means bookmark functions ignore case in completion.") -(defvar bookmark-search-size 500 "Length, in characters, of the -context strings recorded on either side of a bookmark.") +(defvar bookmark-search-size 500 + "Length of the context strings recorded on either side of a bookmark.") (defvar bookmark-alist () "Association list of bookmarks. @@ -170,15 +165,17 @@ instead, let the various bookmark functions do it for you.") (defvar bookmark-current-buffer nil) (defun bookmark-set (&optional parg) - "Set a bookmark named NAME inside a file. 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 bookmark with name NAME would -be the one in effect at any given time, but the others are still there, -should you decide to delete the most recent one. + + "Set a bookmark named NAME inside a file. +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 +bookmark with name NAME would be the one in effect at any given time, +but the others are still there, should you decide to delete the most +recent one. To yank words from the text of the buffer and use them as part of the -bookmark name, type C-w while setting a bookmark. Successive C-w\'s +bookmark name, type C-w while setting a bookmark. Successive C-w's yank successive words. Typing C-v inserts the name of the current file being visited. Typing @@ -305,10 +302,10 @@ the list of bookmarks.\)" (bookmark-load bookmark-file))) (defun bookmark-jump (str) - "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 -bookmarks. See help on function \`bookmark-load\' for more about + "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 +bookmarks. See help on function `bookmark-load' for more about this." (interactive (let ((completion-ignore-case bookmark-completion-ignore-case)) @@ -347,8 +344,8 @@ this." "\"")))))) (defun bookmark-locate (str) - "Insert the name of the file associated with BOOKMARK \(as opposed -to the contents of that file\)." + "Insert the name of the file associated with BOOKMARK. +\(This is not the same as the contents of that file\)." (interactive (let ((completion-ignore-case bookmark-completion-ignore-case)) (list (completing-read @@ -358,11 +355,18 @@ to the contents of that file\)." 0)))) (insert (car (car (cdr (assoc str bookmark-alist)))))) -(defun bookmark-rename (old) - "Change the name of BOOKMARK to NEWNAME. While you are entering -the new name, consecutive C-w\'s will insert consectutive words from -the text of the buffer into the new bookmark name, and C-v will insert -the name of the file." +(defun bookmark-rename (old &optional new) + "Change the name of BOOKMARK to NEWNAME. +If called from keyboard, prompts for OLD and NEWNAME. +If called from menubar, prompts for NEWNAME. +If called from Lisp, prompts for NEWNAME if only BOOKMARK was passed +as an argument. If called with two strings, then no prompting is +done. You must pass at least 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, and C-v inserts the name of the file." + (interactive (let ((completion-ignore-case bookmark-completion-ignore-case)) (list (completing-read "Old bookmark name: " @@ -375,15 +379,16 @@ the name of the file." (setq bookmark-current-buffer (current-buffer)) (let ((cell (assoc old bookmark-alist)) (str - (read-from-minibuffer - "New name: " - nil - (let ((now-map (copy-keymap minibuffer-local-map))) - (progn (define-key now-map "\C-w" - 'bookmark-yank-word) - (define-key now-map "\C-v" - 'bookmark-insert-current-file-name)) - now-map)))) + (or new ; use second arg, if non-nil + (read-from-minibuffer + "New name: " + nil + (let ((now-map (copy-keymap minibuffer-local-map))) + (progn (define-key now-map "\C-w" + 'bookmark-yank-word) + (define-key now-map "\C-v" + 'bookmark-insert-current-file-name)) + now-map))))) (progn (setcar cell str) (setq bookmark-current-bookmark str) @@ -393,10 +398,10 @@ the name of the file." (bookmark-save)))))) (defun bookmark-insert (str) - "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 + "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 (let ((completion-ignore-case bookmark-completion-ignore-case)) @@ -426,11 +431,12 @@ this." "\"")))))) (defun bookmark-delete (str) - "Delete the bookmark named NAME from the bookmark list. 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\)." + "Delete the bookmark named NAME from the bookmark list. +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\)." + (interactive (let ((completion-ignore-case bookmark-completion-ignore-case)) (list @@ -471,8 +477,9 @@ recently used in this file, if any\)." (bookmark-save t)) (defun bookmark-save (&optional parg file) - "Save currently defined bookmarks in the file defined by the -variable \`bookmark-file\'. With a prefix arg, save it in file FILE. + "Save currently defined bookmarks. +Saves by default in the file defined by the variable +`bookmark-file'. With a prefix arg, save it in file FILE. 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 @@ -481,9 +488,9 @@ instead. If you pass in one argument, and it is non-nil, then the user will be interactively queried for a file to save in. When you want to load in the bookmarks from a file, use -\\`bookmark-load\\', \\[bookmark-load]. That function will prompt you +\`bookmark-load\', \\[bookmark-load]. That function will prompt you for a file, defaulting to the file defined by variable -\`bookmark-file\'." +`bookmark-file'." (interactive "P") (cond ((and (null parg) (null file)) @@ -514,15 +521,16 @@ for a file, defaulting to the file defined by variable (kill-buffer (current-buffer)))) (defun bookmark-load (file &optional revert no-msg) - "Loads bookmarks from FILE, appending loaded bookmarks to the front -of the list of bookmarks. If optional second argument REVERT is -non-nil, existing bookmarks are destroyed. Optional third arg NO-MSG -means don't display any messages while loading. + "Load bookmarks from FILE (which must be in bookmark format). +Appends loaded bookmarks to the front of the list of bookmarks. If +optional second argument REVERT is non-nil, existing bookmarks are +destroyed. Optional third arg NO-MSG means don't display any messages +while loading. If you load a file that doesn't contain a proper bookmark alist, you -will corrupt Emacs\' bookmark list. Generally, you should only load +will corrupt Emacs's bookmark list. Generally, you should only load in files that were created with the bookmark functions in the first -place. Your own personal bookmark file, \`~/.emacs-bkmrks\', is +place. Your own personal bookmark file, `~/.emacs-bkmrks', is maintained automatically by Emacs; you shouldn't need to load it explicitly." (interactive @@ -558,12 +566,13 @@ explicitly." ;;;; bookmark menu bar stuff ;;;; -(defvar bookmark-menu-bar-length 70 "*Maximum length of a bookmark name -displayed on a popup menu.") +(defvar bookmark-menu-bar-length 70 + "*Maximum length of a bookmark name displayed on a popup menu.") (defvar bookmark-enable-menu-bar t - "*Non-nil means put a bookmark menu on the menu bar \(assuming that -you are running Emacs under a windowing system, such as X\).") + "*Non-nil means put a bookmark menu on the menu bar. +\(Assuming that you are running Emacs under a windowing system, such +as X.\)") (defun bookmark-make-menu-bar-alist () (if (not bookmark-alist) @@ -594,7 +603,11 @@ you are running Emacs under a windowing system, such as X\).") (apply func-sym (list str))))) (defun bookmark-menu-bar-insert (event) - ;; see bookmark-insert + "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 "e") (bookmark-make-menu-bar-with-function 'bookmark-insert "Bookmark Insert Menu" @@ -602,7 +615,11 @@ you are running Emacs under a windowing system, such as X\).") event)) (defun bookmark-menu-bar-jump (event) - ;; see bookmark-jump + "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 +bookmarks. See help on function `bookmark-load' for more about +this." (interactive "e") (bookmark-make-menu-bar-with-function 'bookmark-jump "Bookmark Jump Menu" @@ -610,7 +627,8 @@ you are running Emacs under a windowing system, such as X\).") event)) (defun bookmark-menu-bar-locate (event) - ;; see bookmark-locate + "Insert the name of the file associated with BOOKMARK. +\(This is not the same as the contents of that file\)." (interactive "e") (bookmark-make-menu-bar-with-function 'bookmark-locate "Bookmark Locate Menu" @@ -618,7 +636,16 @@ you are running Emacs under a windowing system, such as X\).") event)) (defun bookmark-menu-bar-rename (event) - ;; see bookmark-rename + "Change the name of BOOKMARK to NEWNAME. +If called from keyboard, prompts for OLD and NEWNAME. +If called from menubar, prompts for NEWNAME. +If called from Lisp, prompts for NEWNAME if only BOOKMARK was passed +as an argument. If called with two strings, then no prompting is +done. You must pass at least 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, and C-v inserts the name of the file." (interactive "e") (bookmark-make-menu-bar-with-function 'bookmark-rename "Bookmark Rename Menu" @@ -626,7 +653,11 @@ you are running Emacs under a windowing system, such as X\).") event)) (defun bookmark-menu-bar-delete (event) - ;; see bookmark-delete + "Delete the bookmark named NAME from the bookmark list. +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\)." (interactive "e") (bookmark-make-menu-bar-with-function 'bookmark-delete "Bookmark Delete Menu" |