Commit 13901bcb authored by Karl Fogel's avatar Karl Fogel
Browse files

* bookmark.el

  (bookmark-get-bookmark, bookmark-get-bookmark-record,
   bookmark-set-name, bookmark-prop-get, bookmark-prop-set,
   bookmark-get-annotation, bookmark-set-annotation, bookmark-get-filename,
   bookmark-set-filename, bookmark-get-position, bookmark-set-position,
   bookmark-get-front-context-string, bookmark-set-front-context-string,
   bookmark-get-rear-context-string, bookmark-set-rear-context-string,
   bookmark-location, bookmark-jump, bookmark-jump-other-window,
   bookmark-handle-bookmark, bookmark-relocate, bookmark-insert-location,
   bookmark-rename, bookmark-insert, bookmark-delete, bookmark-time-to-save-p,
   bookmark-edit-annotation-mode, bookmark-edit-annotation): Improve doc
   strings to say whether bookmark can be a string or a record or both,
   and make other consistency and clarity fixes.
  (bookmark-get-handler, bookmark--jump-via, bookmark-write-file,
   bookmark-default-annotation-text, bookmark-yank-word,
   bookmark-maybe-load-default-file, bookmark-maybe-sort-alist,
   bookmark-import-new-list, bookmark-maybe-rename,
   bookmark-bmenu-show-filenames, bookmark-bmenu-hide-filenames,
   bookmark-bmenu-bookmark): Give these doc strings.
  (bookmark-bmenu-check-position): Give this a doc string, but also
   add a FIXME comment about how the function may be pointless.
  (bookmark-default-handler): Rework doc string and change a parameter
   name, to clarify that this takes a bookmark record not a bookmark name.
  (bookmark-set): Change a parameter name to indicate its meaning,
   and improve the doc string a bit.
(Bug#4188)
parent 5c1b3e94
2009-10-04 Karl Fogel <kfogel@red-bean.com>
* bookmark.el (bookmark-get-bookmark, bookmark-get-bookmark-record,
bookmark-set-name, bookmark-prop-get, bookmark-prop-set,
bookmark-get-annotation, bookmark-set-annotation,
bookmark-get-filename, bookmark-set-filename, bookmark-get-position,
bookmark-set-position, bookmark-get-front-context-string,
bookmark-set-front-context-string, bookmark-get-rear-context-string,
bookmark-set-rear-context-string, bookmark-location, bookmark-jump,
bookmark-jump-other-window, bookmark-handle-bookmark,
bookmark-relocate, bookmark-insert-location, bookmark-rename,
bookmark-insert, bookmark-delete, bookmark-time-to-save-p,
bookmark-edit-annotation-mode, bookmark-edit-annotation): Improve
doc strings to say whether bookmark can be a string or a record
or both, and make other consistency and clarity fixes.
(bookmark-get-handler, bookmark--jump-via, bookmark-write-file
bookmark-default-annotation-text, bookmark-yank-word,
bookmark-maybe-load-default-file, bookmark-maybe-sort-alist,
bookmark-import-new-list, bookmark-maybe-rename,
bookmark-bmenu-show-filenames, bookmark-bmenu-hide-filenames,
bookmark-bmenu-bookmark): Give these doc strings.
(bookmark-bmenu-check-position): Give this a doc string, but also
add a FIXME comment about how the function may be pointless.
(bookmark-default-handler): Rework doc string and change a
parameter name, to clarify that this takes a bookmark record
not a bookmark name.
(bookmark-set): Change a parameter name to indicate its meaning,
and improve the doc string a bit.
(Bug#4188)
2009-10-04 Karl Fogel <kfogel@red-bean.com> 2009-10-04 Karl Fogel <kfogel@red-bean.com>
* bookmark.el (bookmark-alist): Document the new `handler' element * bookmark.el (bookmark-alist): Document the new `handler' element
......
...@@ -325,8 +325,9 @@ through a file easier.") ...@@ -325,8 +325,9 @@ through a file easier.")
(defun bookmark-get-bookmark (bookmark &optional noerror) (defun bookmark-get-bookmark (bookmark &optional noerror)
"Return the bookmark record corresponding to BOOKMARK. "Return the bookmark record corresponding to BOOKMARK.
If BOOKMARK is already a bookmark record, just return it, If BOOKMARK is a string, look for the corresponding bookmark record in
Otherwise look for the corresponding bookmark in `bookmark-alist'." `bookmark-alist'; return it if found, otherwise error. Else if
BOOKMARK is already a bookmark record, just return it."
(cond (cond
((consp bookmark) bookmark) ((consp bookmark) bookmark)
((stringp bookmark) ((stringp bookmark)
...@@ -335,8 +336,9 @@ Otherwise look for the corresponding bookmark in `bookmark-alist'." ...@@ -335,8 +336,9 @@ Otherwise look for the corresponding bookmark in `bookmark-alist'."
(defun bookmark-get-bookmark-record (bookmark) (defun bookmark-get-bookmark-record (bookmark)
"Return the guts of the entry for BOOKMARK in `bookmark-alist'. "Return the record portion of the entry for BOOKMARK in
That is, all information but the name." `bookmark-alist' (that is, all information but the name).
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(let ((alist (cdr (bookmark-get-bookmark bookmark)))) (let ((alist (cdr (bookmark-get-bookmark bookmark))))
;; The bookmark objects can either look like (NAME ALIST) or ;; The bookmark objects can either look like (NAME ALIST) or
;; (NAME . ALIST), so we have to distinguish the two here. ;; (NAME . ALIST), so we have to distinguish the two here.
...@@ -345,17 +347,20 @@ That is, all information but the name." ...@@ -345,17 +347,20 @@ That is, all information but the name."
(defun bookmark-set-name (bookmark newname) (defun bookmark-set-name (bookmark newname)
"Set BOOKMARK's name to NEWNAME." "Set BOOKMARK's name to NEWNAME.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(setcar (setcar
(if (stringp bookmark) (bookmark-get-bookmark bookmark) bookmark) (if (stringp bookmark) (bookmark-get-bookmark bookmark) bookmark)
newname)) newname))
(defun bookmark-prop-get (bookmark prop) (defun bookmark-prop-get (bookmark prop)
"Return the property PROP of BOOKMARK, or nil if none." "Return the property PROP of BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(cdr (assq prop (bookmark-get-bookmark-record bookmark)))) (cdr (assq prop (bookmark-get-bookmark-record bookmark))))
(defun bookmark-prop-set (bookmark prop val) (defun bookmark-prop-set (bookmark prop val)
"Set the property PROP of BOOKMARK to VAL." "Set the property PROP of BOOKMARK to VAL.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(let ((cell (assq prop (bookmark-get-bookmark-record bookmark)))) (let ((cell (assq prop (bookmark-get-bookmark-record bookmark))))
(if cell (if cell
(setcdr cell val) (setcdr cell val)
...@@ -363,55 +368,67 @@ That is, all information but the name." ...@@ -363,55 +368,67 @@ That is, all information but the name."
(list (cons prop val)))))) (list (cons prop val))))))
(defun bookmark-get-annotation (bookmark) (defun bookmark-get-annotation (bookmark)
"Return the annotation of BOOKMARK, or nil if none." "Return the annotation of BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-get bookmark 'annotation)) (bookmark-prop-get bookmark 'annotation))
(defun bookmark-set-annotation (bookmark ann) (defun bookmark-set-annotation (bookmark ann)
"Set the annotation of BOOKMARK to ANN." "Set the annotation of BOOKMARK to ANN.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-set bookmark 'annotation ann)) (bookmark-prop-set bookmark 'annotation ann))
(defun bookmark-get-filename (bookmark) (defun bookmark-get-filename (bookmark)
"Return the full filename of BOOKMARK." "Return the full filename of BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-get bookmark 'filename)) (bookmark-prop-get bookmark 'filename))
(defun bookmark-set-filename (bookmark filename) (defun bookmark-set-filename (bookmark filename)
"Set the full filename of BOOKMARK to FILENAME." "Set the full filename of BOOKMARK to FILENAME.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-set bookmark 'filename filename)) (bookmark-prop-set bookmark 'filename filename))
(defun bookmark-get-position (bookmark) (defun bookmark-get-position (bookmark)
"Return the position \(i.e.: point\) of BOOKMARK." "Return the position \(i.e.: point\) of BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-get bookmark 'position)) (bookmark-prop-get bookmark 'position))
(defun bookmark-set-position (bookmark position) (defun bookmark-set-position (bookmark position)
"Set the position \(i.e.: point\) of BOOKMARK to POSITION." "Set the position \(i.e.: point\) of BOOKMARK to POSITION.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-set bookmark 'position position)) (bookmark-prop-set bookmark 'position position))
(defun bookmark-get-front-context-string (bookmark) (defun bookmark-get-front-context-string (bookmark)
"Return the front-context-string of BOOKMARK." "Return the front-context-string of BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-get bookmark 'front-context-string)) (bookmark-prop-get bookmark 'front-context-string))
(defun bookmark-set-front-context-string (bookmark string) (defun bookmark-set-front-context-string (bookmark string)
"Set the front-context-string of BOOKMARK to STRING." "Set the front-context-string of BOOKMARK to STRING.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-set bookmark 'front-context-string string)) (bookmark-prop-set bookmark 'front-context-string string))
(defun bookmark-get-rear-context-string (bookmark) (defun bookmark-get-rear-context-string (bookmark)
"Return the rear-context-string of BOOKMARK." "Return the rear-context-string of BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-get bookmark 'rear-context-string)) (bookmark-prop-get bookmark 'rear-context-string))
(defun bookmark-set-rear-context-string (bookmark string) (defun bookmark-set-rear-context-string (bookmark string)
"Set the rear-context-string of BOOKMARK to STRING." "Set the rear-context-string of BOOKMARK to STRING.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-set bookmark 'rear-context-string string)) (bookmark-prop-set bookmark 'rear-context-string string))
(defun bookmark-get-handler (bookmark) (defun bookmark-get-handler (bookmark)
"Return the handler function for BOOKMARK, or nil if none.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-prop-get bookmark 'handler)) (bookmark-prop-get bookmark 'handler))
(defvar bookmark-history nil (defvar bookmark-history nil
...@@ -715,27 +732,28 @@ This expects to be called from `point-min' in a bookmark file." ...@@ -715,27 +732,28 @@ This expects to be called from `point-min' in a bookmark file."
map)) map))
;;;###autoload ;;;###autoload
(defun bookmark-set (&optional name parg) (defun bookmark-set (&optional name no-overwrite)
"Set a bookmark named NAME inside a file. "Set a bookmark named NAME inside a file.
If name is nil, then the user will be prompted. If name is nil, then prompt the user.
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\" With prefix arg (NO-OVERWRITE), do not overwrite a bookmark that
the new bookmark onto the bookmark alist. Thus the most recently set has the same name as NAME if such a bookmark already exists, but
bookmark with name NAME would be the one in effect at any given time, instead \"push\" the new bookmark onto the bookmark alist. Thus
but the others are still there, should you decide to delete the most the most recently set bookmark with name NAME would be the one in
recent one. effect at any given time, but the others are still there, should
the user decide to delete the most recent one.
To yank words from the text of the buffer and use them as part of the 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. yank successive words.
Typing C-u inserts the name of the last bookmark used in the buffer Typing C-u inserts the name of the last bookmark used in the buffer
\(as an aid in using a single bookmark name to track your progress \(as an aid in using a single bookmark name to track progress through
through a large file\). If no bookmark was used, then C-u inserts the a large file\). If no bookmark was used, then C-u inserts the name of
name of the file being visited. the file being visited.
Use \\[bookmark-delete] to remove bookmarks \(you give it a name, Use \\[bookmark-delete] to remove bookmarks \(give it a name and it
and it removes only the first instance of a bookmark with that name from removes only the first instance of a bookmark with that name from
the list of bookmarks.\)" the list of bookmarks.\)"
(interactive (list nil current-prefix-arg)) (interactive (list nil current-prefix-arg))
(let* ((record (bookmark-make-record)) (let* ((record (bookmark-make-record))
...@@ -755,7 +773,7 @@ the list of bookmarks.\)" ...@@ -755,7 +773,7 @@ the list of bookmarks.\)"
bookmark-minibuffer-read-name-map bookmark-minibuffer-read-name-map
nil nil default)))) nil nil default))))
(and (string-equal str "") (setq str default)) (and (string-equal str "") (setq str default))
(bookmark-store str (cdr record) parg) (bookmark-store str (cdr record) no-overwrite)
;; Ask for an annotation buffer for this bookmark ;; Ask for an annotation buffer for this bookmark
(if bookmark-use-annotations (if bookmark-use-annotations
...@@ -780,6 +798,9 @@ whose annotation is being edited.") ...@@ -780,6 +798,9 @@ whose annotation is being edited.")
(defun bookmark-default-annotation-text (bookmark) (defun bookmark-default-annotation-text (bookmark)
"Return default annotation text for BOOKMARK (a string, not a record).
The default annotation text is simply some text explaining how to use
annotations."
(concat "# Type the annotation for bookmark '" bookmark "' here.\n" (concat "# Type the annotation for bookmark '" bookmark "' here.\n"
"# All lines which start with a '#' will be deleted.\n" "# All lines which start with a '#' will be deleted.\n"
"# Type C-c C-c when done.\n#\n" "# Type C-c C-c when done.\n#\n"
...@@ -806,6 +827,8 @@ It takes one argument, the name of the bookmark, as a string.") ...@@ -806,6 +827,8 @@ It takes one argument, the name of the bookmark, as a string.")
"Mode for editing the annotation of bookmark BOOKMARK. "Mode for editing the annotation of bookmark BOOKMARK.
When you have finished composing, type \\[bookmark-send-annotation]. When you have finished composing, type \\[bookmark-send-annotation].
BOOKMARK is a bookmark name (a string) or a bookmark record.
\\{bookmark-edit-annotation-mode-map}" \\{bookmark-edit-annotation-mode-map}"
(interactive) (interactive)
(kill-all-local-variables) (kill-all-local-variables)
...@@ -842,7 +865,8 @@ Lines beginning with `#' are ignored." ...@@ -842,7 +865,8 @@ Lines beginning with `#' are ignored."
(defun bookmark-edit-annotation (bookmark) (defun bookmark-edit-annotation (bookmark)
"Pop up a buffer for editing bookmark BOOKMARK's annotation." "Pop up a buffer for editing bookmark BOOKMARK's annotation.
BOOKMARK is a bookmark name (a string) or a bookmark record."
(pop-to-buffer (generate-new-buffer-name "*Bookmark Annotation Compose*")) (pop-to-buffer (generate-new-buffer-name "*Bookmark Annotation Compose*"))
(bookmark-edit-annotation-mode bookmark)) (bookmark-edit-annotation-mode bookmark))
...@@ -880,9 +904,9 @@ Default to file name if it's nil." ...@@ -880,9 +904,9 @@ Default to file name if it's nil."
(defun bookmark-yank-word () (defun bookmark-yank-word ()
"Get the next word from the buffer and append it to the name of the
bookmark currently being set, advancing point by one word."
(interactive) (interactive)
;; get the next word from the buffer and append it to the name of
;; the bookmark currently being set.
(let ((string (with-current-buffer bookmark-current-buffer (let ((string (with-current-buffer bookmark-current-buffer
(goto-char bookmark-yank-point) (goto-char bookmark-yank-point)
(buffer-substring-no-properties (buffer-substring-no-properties
...@@ -908,6 +932,7 @@ Default to file name if it's nil." ...@@ -908,6 +932,7 @@ Default to file name if it's nil."
(defun bookmark-maybe-load-default-file () (defun bookmark-maybe-load-default-file ()
"If bookmarks have not been loaded from the default place, load them."
(and (not bookmarks-already-loaded) (and (not bookmarks-already-loaded)
(null bookmark-alist) (null bookmark-alist)
(prog2 (prog2
...@@ -927,8 +952,8 @@ Default to file name if it's nil." ...@@ -927,8 +952,8 @@ Default to file name if it's nil."
(defun bookmark-maybe-sort-alist () (defun bookmark-maybe-sort-alist ()
;;Return the bookmark-alist for display. If the bookmark-sort-flag "Return `bookmark-alist' for display.
;;is non-nil, then return a sorted copy of the alist. If `bookmark-sort-flag' is non-nil, then return a sorted copy of the alist."
(if bookmark-sort-flag (if bookmark-sort-flag
(sort (copy-alist bookmark-alist) (sort (copy-alist bookmark-alist)
(function (function
...@@ -941,6 +966,12 @@ Default to file name if it's nil." ...@@ -941,6 +966,12 @@ Default to file name if it's nil."
Useful for example to unhide text in `outline-mode'.") Useful for example to unhide text in `outline-mode'.")
(defun bookmark--jump-via (bookmark display-function) (defun bookmark--jump-via (bookmark display-function)
"Handle BOOKMARK, then call DISPLAY-FUNCTION with current buffer as argument.
Bookmark may be a bookmark name (a string) or a bookmark record.
After calling DISPLAY-FUNCTION, set window point to the point specified
by BOOKMARK, if necessary, run `bookmark-after-jump-hook', and then show
any annotations for this bookmark."
(bookmark-handle-bookmark bookmark) (bookmark-handle-bookmark bookmark)
(save-current-buffer (save-current-buffer
(funcall display-function (current-buffer))) (funcall display-function (current-buffer)))
...@@ -966,7 +997,10 @@ this. ...@@ -966,7 +997,10 @@ this.
If the file pointed to by BOOKMARK no longer exists, you will be asked If the file pointed to by BOOKMARK no longer exists, you will be asked
if you wish to give the bookmark a new location, and `bookmark-jump' if you wish to give the bookmark a new location, and `bookmark-jump'
will then jump to the new location, as well as recording it in place will then jump to the new location, as well as recording it in place
of the old one in the permanent bookmark record." of the old one in the permanent bookmark record.
BOOKMARK may be a bookmark name (a string) or a bookmark record, but
the latter is usually only used by programmatic callers."
(interactive (interactive
(list (bookmark-completing-read "Jump to bookmark" (list (bookmark-completing-read "Jump to bookmark"
bookmark-current-bookmark))) bookmark-current-bookmark)))
...@@ -978,8 +1012,7 @@ of the old one in the permanent bookmark record." ...@@ -978,8 +1012,7 @@ of the old one in the permanent bookmark record."
;;;###autoload ;;;###autoload
(defun bookmark-jump-other-window (bookmark) (defun bookmark-jump-other-window (bookmark)
"Jump to BOOKMARK (a point in some file) in another window. "Jump to BOOKMARK in another window. See `bookmark-jump' for more."
See `bookmark-jump'."
(interactive (interactive
(let ((bkm (bookmark-completing-read "Jump to bookmark (in another window)" (let ((bkm (bookmark-completing-read "Jump to bookmark (in another window)"
bookmark-current-bookmark))) bookmark-current-bookmark)))
...@@ -1014,6 +1047,8 @@ be retrieved from a VC backend, else return nil." ...@@ -1014,6 +1047,8 @@ be retrieved from a VC backend, else return nil."
"Return the location pointed to by the bookmark BOOKMARK. "Return the location pointed to by the bookmark BOOKMARK.
The return value has the form (BUFFER . POINT). The return value has the form (BUFFER . POINT).
BOOKMARK may be a bookmark name (a string) or a bookmark record.
Note: this function is deprecated and is present for Emacs 22 Note: this function is deprecated and is present for Emacs 22
compatibility only." compatibility only."
(save-excursion (save-excursion
...@@ -1025,8 +1060,8 @@ compatibility only." ...@@ -1025,8 +1060,8 @@ compatibility only."
(defun bookmark-handle-bookmark (bookmark) (defun bookmark-handle-bookmark (bookmark)
"Call BOOKMARK's handler or `bookmark-default-handler' if it has none. "Call BOOKMARK's handler or `bookmark-default-handler' if it has none.
Changes current buffer and point and returns nil, or signals a `file-error'. Changes current buffer and point and returns nil, or signals a `file-error'.
BOOKMARK can be a bookmark record used internally by some other
elisp package, or the name of a bookmark to be found in `bookmark-alist'." BOOKMARK may be a bookmark name (a string) or a bookmark record."
(condition-case err (condition-case err
(funcall (or (bookmark-get-handler bookmark) (funcall (or (bookmark-get-handler bookmark)
'bookmark-default-handler) 'bookmark-default-handler)
...@@ -1060,15 +1095,15 @@ elisp package, or the name of a bookmark to be found in `bookmark-alist'." ...@@ -1060,15 +1095,15 @@ elisp package, or the name of a bookmark to be found in `bookmark-alist'."
(setq bookmark-current-bookmark bookmark)) (setq bookmark-current-bookmark bookmark))
nil) nil)
(defun bookmark-default-handler (bmk) (defun bookmark-default-handler (bmk-record)
"Default handler to jump to a particular bookmark location. "Default handler to jump to a particular bookmark location.
BMK is a bookmark record. BMK-RECORD is a bookmark record, not a bookmark name (i.e., not a string).
Changes current buffer and point and returns nil, or signals a `file-error'." Changes current buffer and point and returns nil, or signals a `file-error'."
(let* ((file (bookmark-get-filename bmk)) (let* ((file (bookmark-get-filename bmk-record))
(buf (bookmark-prop-get bmk 'buffer)) (buf (bookmark-prop-get bmk-record 'buffer))
(forward-str (bookmark-get-front-context-string bmk)) (forward-str (bookmark-get-front-context-string bmk-record))
(behind-str (bookmark-get-rear-context-string bmk)) (behind-str (bookmark-get-rear-context-string bmk-record))
(place (bookmark-get-position bmk))) (place (bookmark-get-position bmk-record)))
;; FIXME: bookmark-file-or-variation-thereof was needed for Info files, ;; FIXME: bookmark-file-or-variation-thereof was needed for Info files,
;; but now that Info bookmarks are handled elsewhere it seems that we ;; but now that Info bookmarks are handled elsewhere it seems that we
;; should be able to get rid of it. --Stef ;; should be able to get rid of it. --Stef
...@@ -1076,7 +1111,7 @@ Changes current buffer and point and returns nil, or signals a `file-error'." ...@@ -1076,7 +1111,7 @@ Changes current buffer and point and returns nil, or signals a `file-error'."
(setq file (bookmark-file-or-variation-thereof file)))) (setq file (bookmark-file-or-variation-thereof file))))
(signal 'file-error (signal 'file-error
`("Jumping to bookmark" "No such file or directory" `("Jumping to bookmark" "No such file or directory"
(bookmark-get-filename bmk))) (bookmark-get-filename bmk-record)))
(set-buffer (or buf (find-file-noselect file))) (set-buffer (or buf (find-file-noselect file)))
(if place (goto-char place)) (if place (goto-char place))
...@@ -1096,6 +1131,8 @@ Changes current buffer and point and returns nil, or signals a `file-error'." ...@@ -1096,6 +1131,8 @@ Changes current buffer and point and returns nil, or signals a `file-error'."
;;;###autoload ;;;###autoload
(defun bookmark-relocate (bookmark) (defun bookmark-relocate (bookmark)
"Relocate BOOKMARK to another file (reading file name with minibuffer). "Relocate BOOKMARK to another file (reading file name with minibuffer).
BOOKMARK is a bookmark name (a string), not a bookmark record.
This makes an already existing bookmark point to that file, instead of This 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 the one it used to point at. Useful when a file has been renamed
after a bookmark was set in it." after a bookmark was set in it."
...@@ -1118,6 +1155,8 @@ after a bookmark was set in it." ...@@ -1118,6 +1155,8 @@ after a bookmark was set in it."
;;;###autoload ;;;###autoload
(defun bookmark-insert-location (bookmark &optional no-history) (defun bookmark-insert-location (bookmark &optional no-history)
"Insert the name of the file associated with BOOKMARK. "Insert the name of the file associated with BOOKMARK.
BOOKMARK is a bookmark name (a string), not a bookmark record.
Optional second arg NO-HISTORY means don't record this in the Optional second arg NO-HISTORY means don't record this in the
minibuffer history list `bookmark-history'." minibuffer history list `bookmark-history'."
(interactive (list (bookmark-completing-read "Insert bookmark location"))) (interactive (list (bookmark-completing-read "Insert bookmark location")))
...@@ -1139,7 +1178,8 @@ minibuffer history list `bookmark-history'." ...@@ -1139,7 +1178,8 @@ minibuffer history list `bookmark-history'."
(defalias 'bookmark-locate 'bookmark-insert-location) (defalias 'bookmark-locate 'bookmark-insert-location)
(defun bookmark-location (bookmark) (defun bookmark-location (bookmark)
"Return the name of the file associated with BOOKMARK." "Return the name of the file associated with BOOKMARK.
BOOKMARK may be a bookmark name (a string) or a bookmark record."
(bookmark-maybe-load-default-file) (bookmark-maybe-load-default-file)
(bookmark-get-filename bookmark)) (bookmark-get-filename bookmark))
...@@ -1150,6 +1190,8 @@ minibuffer history list `bookmark-history'." ...@@ -1150,6 +1190,8 @@ minibuffer history list `bookmark-history'."
If called from keyboard, prompt for OLD and NEW. If called from If called from keyboard, prompt for OLD and NEW. If called from
menubar, select OLD from a menu and prompt for NEW. menubar, select OLD from a menu and prompt for NEW.
Both OLD and NEW are bookmark names (strings), never bookmark records.
If called from Lisp, prompt for NEW if only OLD was passed as an If called from Lisp, prompt for NEW if only OLD was passed as an
argument. If called with two strings, then no prompting is done. You argument. If called with two strings, then no prompting is done. You
must pass at least OLD when calling from Lisp. must pass at least OLD when calling from Lisp.
...@@ -1186,6 +1228,8 @@ name." ...@@ -1186,6 +1228,8 @@ name."
;;;###autoload ;;;###autoload
(defun bookmark-insert (bookmark) (defun bookmark-insert (bookmark)
"Insert the text of the file pointed to by bookmark BOOKMARK. "Insert the text of the file pointed to by bookmark BOOKMARK.
BOOKMARK is a bookmark name (a string), not a bookmark record.
You may have a problem using this function if the value of variable 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 `bookmark-alist' is nil. If that happens, you need to load in some
bookmarks. See help on function `bookmark-load' for more about bookmarks. See help on function `bookmark-load' for more about
...@@ -1206,6 +1250,8 @@ this." ...@@ -1206,6 +1250,8 @@ this."
;;;###autoload ;;;###autoload
(defun bookmark-delete (bookmark &optional batch) (defun bookmark-delete (bookmark &optional batch)
"Delete BOOKMARK from the bookmark list. "Delete BOOKMARK from the bookmark list.
BOOKMARK is a bookmark name (a string), not a bookmark record.
Removes only the first instance of a bookmark with that name. If 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 there are one or more other bookmarks with the same name, they will
not be deleted. Defaults to the \"current\" bookmark \(that is, the not be deleted. Defaults to the \"current\" bookmark \(that is, the
...@@ -1233,14 +1279,13 @@ probably because we were called from there." ...@@ -1233,14 +1279,13 @@ probably because we were called from there."
(bookmark-save)))) (bookmark-save))))
(defun bookmark-time-to-save-p (&optional last-time) (defun bookmark-time-to-save-p (&optional final-time)
;; By Gregory M. Saunders <saunders@cis.ohio-state.edu> "Return t if it is time to save bookmarks to disk, nil otherwise.
;; finds out whether it's time to save bookmarks to a file, by Optional argument FINAL-TIME means this is being called when Emacs
;; examining the value of variable bookmark-save-flag, and maybe is being killed, so save even if `bookmark-save-flag' is a number and
;; bookmark-alist-modification-count. Returns t if they should be is greater than `bookmark-alist-modification-count'."
;; saved, nil otherwise. if last-time is non-nil, then this is ;; By Gregory M. Saunders <saunders{_AT_}cis.ohio-state.edu>
;; being called when emacs is killed. (cond (final-time
(cond (last-time
(and (> bookmark-alist-modification-count 0) (and (> bookmark-alist-modification-count 0)
bookmark-save-flag)) bookmark-save-flag))
((numberp bookmark-save-flag) ((numberp bookmark-save-flag)
...@@ -1298,6 +1343,7 @@ for a file, defaulting to the file defined by variable ...@@ -1298,6 +1343,7 @@ for a file, defaulting to the file defined by variable
(defun bookmark-write-file (file) (defun bookmark-write-file (file)
"Write `bookmark-alist' to FILE."
(bookmark-maybe-message "Saving bookmarks to file %s..." file) (bookmark-maybe-message "Saving bookmarks to file %s..." file)
(with-current-buffer (get-buffer-create " *Bookmarks*") (with-current-buffer (get-buffer-create " *Bookmarks*")
(goto-char (point-min)) (goto-char (point-min))
...@@ -1326,10 +1372,8 @@ for a file, defaulting to the file defined by variable ...@@ -1326,10 +1372,8 @@ for a file, defaulting to the file defined by variable
(defun bookmark-import-new-list (new-list) (defun bookmark-import-new-list (new-list)
;; Walk over the new list, adding each individual bookmark "Add NEW-LIST of bookmarks to `bookmark-alist', rename new bookmarks
;; carefully. "Carefully" means checking against the existing with \"<N>\" extensions where they collide with existing bookmark names."
;; bookmark-alist and renaming the new bookmarks with <N> extensions
;; as necessary.
(let ((lst new-list) (let ((lst new-list)
(names (bookmark-all-names))) (names (bookmark-all-names)))
(while lst (while lst
...@@ -1341,11 +1385,8 @@ for a file, defaulting to the file defined by variable ...@@ -1341,11 +1385,8 @@ for a file, defaulting to the file defined by variable
(defun bookmark-maybe-rename (full-record names) (defun bookmark-maybe-rename (full-record names)
;; just a helper for bookmark-import-new-list; it is only for "If bookmark record FULL-RECORD collides with anything in NAMES, give
;; readability that this is not inlined. FULL-RECORD a new name. This is a helper for `bookmark-import-new-list'."
;;
;; Once this has found a free name, it sets full-record to that
;; name.
(let ((found-name (bookmark-name-from-full-record full-record))) (let ((found-name (bookmark-name-from-full-record full-record)))
(if (member found-name names) (if (member found-name names)
;; We've got a conflict, so generate a new name ;; We've got a conflict, so generate a new name
...@@ -1602,6 +1643,10 @@ Optional argument SHOW means show them unconditionally." ...@@ -1602,6 +1643,10 @@ Optional argument SHOW means show them unconditionally."
(defun bookmark-bmenu-show-filenames (&optional force)