Change a return type, for greater extensibility. See

http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01077.html
and its thread for discussion leading to this change.

* emacs-cvs/lisp/bookmark.el:
(bookmark-jump-noselect): Return an alist instead of a dotted pair.
(bookmark-jump, bookmark-jump-other-window, bookmark-insert)
(bookmark-bmenu-2-window, bookmark-bmenu-other-window)
(bookmark-bmenu-switch-other-window): Adjust accordingly.
(bookmark-make-cell-function): Adjust documentation accordingly.

* emacs-cvs/lisp/image-mode.el
(image-bookmark-jump): Adjust return type accordingly; document.

* emacs-cvs/lisp/doc-view.el
(doc-view-bookmark-jump): Adjust return type accordingly; document.

4 files changed, 55 insertions, 30 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 470812daa18..cc089335e4b 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,22 @@
+2008-01-02  Karl Fogel  <kfogel@red-bean.com>
+
+        Change a return type, for greater extensibility.  See
+        http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01077.html
+        and its thread for discussion leading to this change.
+
+        * emacs-cvs/lisp/bookmark.el:
+        (bookmark-jump-noselect): Return an alist instead of a dotted pair.
+        (bookmark-jump, bookmark-jump-other-window, bookmark-insert)
+        (bookmark-bmenu-2-window, bookmark-bmenu-other-window)
+        (bookmark-bmenu-switch-other-window): Adjust accordingly.
+        (bookmark-make-cell-function): Adjust documentation accordingly.
+
+        * emacs-cvs/lisp/image-mode.el
+        (image-bookmark-jump): Adjust return type accordingly; document.
+
+        * emacs-cvs/lisp/doc-view.el
+        (doc-view-bookmark-jump): Adjust return type accordingly; document.
+
 2008-01-02  Miles Bader  <Miles Bader <miles@gnu.org>>
 
         * net/rcirc.el (rcirc-log-filename-function): New variable.
diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 9b8eb738f0c..49749f4e465 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -491,13 +491,11 @@ The function will be called with two arguments: ANNOTATION and
 INFO-NODE.  See `bookmark-make-cell-for-text-file' for a
 description.
 
-The returned record may contain a special cons (handler
-. some-function) which sets the handler function that should be
-used to open this bookmark instead of `bookmark-jump-noselect'.
-It should return a cons (BUFFER . POINT) indicating buffer
-showing the bookmarked location and the value of point in that
-buffer.  Like `bookmark-jump-noselect' the buffer shouldn't be
-selected by the handler.")
+The returned record may contain a special cons (handler . SOME-FUNCTION)
+which sets the handler function that should be used to open this
+bookmark instead of `bookmark-jump-noselect'.  The handler should
+return an alist like the one that function returns, and (of course)
+should likewise not select the buffer.")
 
 (defun bookmark-make (name &optional annotation overwrite info-node)
   "Make a bookmark named NAME.
@@ -1084,10 +1082,10 @@ of the old one in the permanent bookmark record."
   (unless bookmark
     (error "No bookmark specified"))
   (bookmark-maybe-historicize-string bookmark)
-  (let ((cell (bookmark-jump-internal bookmark)))
-    (and cell
-         (switch-to-buffer (car cell))
-         (goto-char (cdr cell))
+  (let ((alist (bookmark-jump-internal bookmark)))
+    (and alist
+         (switch-to-buffer (cadr (assq 'buffer alist)))
+         (goto-char (cadr (assq 'position alist)))
          (progn (run-hooks 'bookmark-after-jump-hook) t)
          (if bookmark-automatically-show-annotations
              ;; if there is an annotation for this bookmark,
@@ -1106,10 +1104,10 @@ See `bookmark-jump'."
          (list bkm) bkm)))
   (when bookmark
     (bookmark-maybe-historicize-string bookmark)
-    (let ((cell (bookmark-jump-internal bookmark)))
-      (and cell
-           (switch-to-buffer-other-window (car cell))
-           (goto-char (cdr cell))
+    (let ((alist (bookmark-jump-internal bookmark)))
+      (and alist
+           (switch-to-buffer-other-window (cadr (assq 'buffer alist)))
+           (goto-char (cadr (assq 'position alist)))
            (if bookmark-automatically-show-annotations
                ;; if there is an annotation for this bookmark,
                ;; show it in a buffer.
@@ -1143,8 +1141,12 @@ be retrieved from a VC backend, else return nil."
            bookmark))
 
 (defun bookmark-jump-noselect (str)
-  ;; a leetle helper for bookmark-jump :-)
-  ;; returns (BUFFER . POINT)
+  ;; Helper for bookmark-jump.  STR is a bookmark name, of the sort
+  ;; accepted by `bookmark-get-bookmark'.
+  ;;
+  ;; Return an alist '((buffer BUFFER) (position POSITION) ...)
+  ;; indicating the bookmarked point within the specied buffer.  Any
+  ;; elements not documented here should be ignored.
   (bookmark-maybe-load-default-file)
   (let* ((file (expand-file-name (bookmark-get-filename str)))
          (forward-str            (bookmark-get-front-context-string str))
@@ -1179,7 +1181,7 @@ be retrieved from a VC backend, else return nil."
                     (goto-char (match-end 0))))
             ;; added by db
             (setq bookmark-current-bookmark str)
-            (cons (current-buffer) (point))))
+            `((buffer ,(current-buffer)) (position ,(point)))))
 
       ;; Else unable to find the marked file, so ask if user wants to
       ;; relocate the bookmark, else remind them to consider deletion.
@@ -1296,7 +1298,7 @@ this."
   (let ((orig-point (point))
         (str-to-insert
          (save-excursion
-           (set-buffer (car (bookmark-jump-internal bookmark)))
+           (set-buffer (cadr (assq 'buffer (bookmark-jump-internal bookmark))))
            (buffer-string))))
     (insert str-to-insert)
     (push-mark)
@@ -1925,9 +1927,9 @@ With a prefix arg, prompts for a file to save them in."
             (pop-up-windows t))
         (delete-other-windows)
         (switch-to-buffer (other-buffer))
-        (let* ((pair (bookmark-jump-internal bmrk))
-               (buff (car pair))
-               (pos  (cdr pair)))
+        (let* ((alist (bookmark-jump-internal bmrk))
+               (buff (cadr (assq 'buffer alist)))
+               (pos  (cadr (assq 'position alist))))
           (pop-to-buffer buff)
           (goto-char pos))
         (bury-buffer menu))))
@@ -1945,9 +1947,9 @@ With a prefix arg, prompts for a file to save them in."
   (interactive)
   (let ((bookmark (bookmark-bmenu-bookmark)))
     (if (bookmark-bmenu-check-position)
-        (let* ((pair (bookmark-jump-internal bookmark))
-               (buff (car pair))
-               (pos  (cdr pair)))
+        (let* ((alist (bookmark-jump-internal bookmark))
+               (buff (cadr (assq 'buffer alist)))
+               (pos  (cadr (assq 'position alist))))
           (switch-to-buffer-other-window buff)
           (goto-char pos)
           (set-window-point (get-buffer-window buff) pos)
@@ -1963,9 +1965,9 @@ The current window remains selected."
         same-window-buffer-names
         same-window-regexps)
     (if (bookmark-bmenu-check-position)
-        (let* ((pair (bookmark-jump-internal bookmark))
-               (buff (car pair))
-               (pos  (cdr pair)))
+        (let* ((alist (bookmark-jump-internal bookmark))
+               (buff (cadr (assq 'buffer alist)))
+               (pos  (cadr (assq 'position alist))))
           (display-buffer buff)
           (let ((o-buffer (current-buffer)))
             ;; save-excursion won't do
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index 388d30b381b..67372f4c621 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -1017,6 +1017,8 @@ See the command `doc-view-mode' for more information on this mode."
 
 ;;;###autoload
 (defun doc-view-bookmark-jump (bmk)
+  ;; This implements the `handler' function interface for record type
+  ;; returned by `bookmark-make-cell-function', which see.
   (save-window-excursion
     (let ((filename (bookmark-get-filename bmk))
           (page (cdr (assq 'page (bookmark-get-bookmark-record bmk)))))
@@ -1024,6 +1026,6 @@ See the command `doc-view-mode' for more information on this mode."
       (when (not (eq major-mode 'doc-view-mode))
         (doc-view-toggle-display))
       (doc-view-goto-page page)
-      (cons (current-buffer) 1))))
+      `((buffer ,(current-buffer)) (position ,1)))))
 
 ;;; doc-view.el ends here
diff --git a/lisp/image-mode.el b/lisp/image-mode.el
index 4041db8ebf2..98f4fa81968 100644
--- a/lisp/image-mode.el
+++ b/lisp/image-mode.el
@@ -375,6 +375,8 @@ and showing the image as an image."
 
 ;;;###autoload
 (defun image-bookmark-jump (bmk)
+  ;; This implements the `handler' function interface for record type
+  ;; returned by `bookmark-make-cell-function', which see.
   (save-window-excursion
     (let ((filename (bookmark-get-filename bmk))
           (type (cdr (assq 'image-type (bookmark-get-bookmark-record bmk))))
@@ -384,7 +386,7 @@ and showing the image as an image."
         (image-toggle-display))
       (when (string= image-type "text")
         (goto-char pos))
-      (cons (current-buffer) pos))))
+      `((buffer ,(current-buffer)) (position ,(point))))))
 
 (provide 'image-mode)