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.

7 files changed, 65 insertions, 35 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index cefab268ec9..c7b263783b5 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,27 @@
+2008-03-07  Karl Fogel  <kfogel@red-bean.com>
+
+        Give a better name to part of the bookmark interface.
+
+        This was originally a much larger change, but halfway through I
+        updated and discovered that Stefan Monnier had done the rest.
+        It looks like he anticipated the new name too, because he used
+        `the-record' instead of `the-cell' for some internal variable names.
+
+        * lisp/bookmark.el
+        (bookmark-make-record-function): Was `bookmark-make-cell-function'.
+        (bookmark-make, bookmark-send-annotation): Update for above.
+        (bookmark-make-record-for-text-file): Was
+        `bookmark-make-cell-for-text-file.  Fix doc string re 2008-03-07T05:00:18Z!monnier@iro.umontreal.ca.
+
+        * lisp/info.el: Adjust accordingly.
+        (Info-bookmark-make-record): Was `Info-bookmark-make-cell'.
+
+        * lisp/image-mode.el: Adjust accordingly.
+        (image-bookmark-make-record): Was `image-bookmark-make-cell'.
+
+        * lisp/doc-view.el: Adjust accordingly.
+        (doc-view-bookmark-make-record): Was `doc-view-bookmark-make-cell'.
+
 2008-03-07  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * bookmark.el (bookmark-map, bookmark-read-annotation-mode-map):
diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 13595b64635..9badaed7f12 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -463,13 +463,14 @@ menus, so `completing-read' never gets a chance to set `bookmark-history'."
     (interactive-p)
     (setq bookmark-history (cons ,string bookmark-history))))
 
-(defvar bookmark-make-cell-function 'bookmark-make-cell-for-text-file
-  "A function that should be called to create the bookmark
-record.  Modes may set this variable buffer-locally to enable
-bookmarking of non-text files like images or pdf documents.
+(defvar bookmark-make-record-function 'bookmark-make-record-for-text-file
+  "A function that should be called to create a bookmark record.
+Modes may set this variable buffer-locally to enable bookmarking of
+locations that should be treated specially, such as Info nodes,
+news posts, images, pdf documents, etc.
 
 The function will be called with one argument: ANNOTATION.
-See `bookmark-make-cell-for-text-file' for a description.
+See `bookmark-make-record-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
@@ -492,7 +493,7 @@ this name."
         ;; already existing bookmark under that name and
         ;; no prefix arg means just overwrite old bookmark
         (setcdr (bookmark-get-bookmark stripped-name)
-                (list (funcall bookmark-make-cell-function annotation)))
+                (list (funcall bookmark-make-record-function annotation)))
 
       ;; otherwise just cons it onto the front (either the bookmark
       ;; doesn't exist already, or there is no prefix arg.  In either
@@ -501,7 +502,7 @@ this name."
       (setq bookmark-alist
             (cons
              (list stripped-name
-                   (funcall bookmark-make-cell-function annotation))
+                   (funcall bookmark-make-record-function annotation))
              bookmark-alist)))
 
     ;; Added by db
@@ -512,12 +513,10 @@ this name."
         (bookmark-save))))
 
 
-(defun bookmark-make-cell-for-text-file (annotation)
+(defun bookmark-make-record-for-text-file (annotation)
   "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 might change someday.
-Optional second arg INFO-NODE means this bookmark is at info node
-INFO-NODE, so record this fact in the bookmark's entry."
+being set (this might change someday)."
   (let ((the-record
          `((filename . ,(bookmark-buffer-file-name))
            (front-context-string
@@ -807,11 +806,12 @@ the bookmark (and file, and point) specified in buffer local variables."
         (bookmark bookmark-annotation-name)
         (pt bookmark-annotation-point)
         (buf bookmark-annotation-buffer))
-    ;; for bookmark-make-cell to work, we need to be
+    ;; for bookmark-make-record-function to work, we need to be
     ;; in the relevant buffer, at the relevant point.
-    ;; Actually, bookmark-make-cell should probably be re-written,
-    ;; to avoid this need.  Should I handle the error if a buffer is
-    ;; killed between "C-x r m" and a "C-c C-c" in the annotation buffer?
+    ;; Actually, the bookmark-make-record-function spec should
+    ;; probably be changed to avoid this need.  Should I handle the
+    ;; error if a buffer is killed between "C-x r m" and a "C-c C-c"
+    ;; in the annotation buffer?
     (save-excursion
       (pop-to-buffer buf)
       (goto-char pt)
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index 50338423218..56ad20c0c41 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -969,7 +969,7 @@ If BACKWARD is non-nil, jump to the previous match."
               (file-name-extension doc-view-buffer-file-name)" files is missing.  "
               "Type \\[doc-view-toggle-display] to switch to an editing mode.")))))
 
-(defvar bookmark-make-cell-function)
+(defvar bookmark-make-record-function)
 
 (defun doc-view-clone-buffer-hook ()
   ;; FIXME: There are several potential problems linked with reconversion
@@ -1046,8 +1046,8 @@ toggle between displaying the document or editing it as text.
   (set (make-local-variable 'cursor-type) nil)
   (use-local-map doc-view-mode-map)
   (set (make-local-variable 'after-revert-hook) 'doc-view-reconvert-doc)
-  (set (make-local-variable 'bookmark-make-cell-function)
-       'doc-view-bookmark-make-cell)
+  (set (make-local-variable 'bookmark-make-record-function)
+       'doc-view-bookmark-make-record)
   (setq mode-name "DocView"
         buffer-read-only t
         major-mode 'doc-view-mode)
@@ -1082,7 +1082,7 @@ See the command `doc-view-mode' for more information on this mode."
 
 ;;;; Bookmark integration
 
-(defun doc-view-bookmark-make-cell (annotation &rest args)
+(defun doc-view-bookmark-make-record (annotation &rest args)
   (let ((the-record
          `((filename . ,buffer-file-name)
            (page     . ,(doc-view-current-page))
@@ -1104,7 +1104,7 @@ 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.
+  ;; returned by `doc-view-bookmark-make-record', which see.
   (save-window-excursion
     (let ((filename (bookmark-get-filename bmk))
           (page (cdr (assq 'page (bookmark-get-bookmark-record bmk)))))
diff --git a/lisp/gnus/ChangeLog b/lisp/gnus/ChangeLog
index 16647a5b10f..d71fcb0e73c 100644
--- a/lisp/gnus/ChangeLog
+++ b/lisp/gnus/ChangeLog
@@ -1,3 +1,9 @@
+2008-03-07  Karl Fogel  <kfogel@red-bean.com>
+
+        * lisp/gnus/gnus-bookmark.el: Adjust for renames in bookmark.el.
+        (gnus-bookmark-make-record): Was `gnus-bookmark-make-cell'.
+        (gnus-bookmark-jump): Adjust some variable names.
+
 2008-03-05  Glenn Morris  <rgm@gnu.org>
 
         * gnus-art.el (gnus-article-mode-line-format-alist): Move to gnus-sum.
diff --git a/lisp/gnus/gnus-bookmark.el b/lisp/gnus/gnus-bookmark.el
index 6b0bfebbabc..41b124e697a 100644
--- a/lisp/gnus/gnus-bookmark.el
+++ b/lisp/gnus/gnus-bookmark.el
@@ -207,13 +207,13 @@ So the cdr of each bookmark is an alist too.")
       (setq gnus-bookmark-alist
             (cons
              (list (gnus-bookmark-remove-properties bmk-name)
-                   (gnus-bookmark-make-cell
+                   (gnus-bookmark-make-record
                     group message-id author date subject annotation))
              gnus-bookmark-alist))))
   (gnus-bookmark-bmenu-surreptitiously-rebuild-list)
   (gnus-bookmark-write-file))
 
-(defun gnus-bookmark-make-cell
+(defun gnus-bookmark-make-record
   (group message-id author date subject annotation)
   "Return the record part of a new bookmark, given GROUP MESSAGE-ID AUTHOR DATE SUBJECT and ANNOTATION."
   (let ((the-record
@@ -288,9 +288,9 @@ So the cdr of each bookmark is an alist too.")
   (let* ((bookmark (or bmk-name
           (completing-read "Jump to bookmarked article: "
                            gnus-bookmark-alist)))
-         (bmk-cell (cadr (assoc bookmark gnus-bookmark-alist)))
-         (group (cdr (assoc 'group bmk-cell)))
-         (message-id (cdr (assoc 'message-id bmk-cell))))
+         (bmk-record (cadr (assoc bookmark gnus-bookmark-alist)))
+         (group (cdr (assoc 'group bmk-record)))
+         (message-id (cdr (assoc 'message-id bmk-record))))
     (when group
       (unless (get-buffer gnus-group-buffer)
         (gnus-no-server))
diff --git a/lisp/image-mode.el b/lisp/image-mode.el
index 23d9aff737d..9a78cb28407 100644
--- a/lisp/image-mode.el
+++ b/lisp/image-mode.el
@@ -278,7 +278,7 @@ This variable is used to display the current image type in the mode line.")
     map)
   "Major mode keymap for viewing images as text in Image mode.")
 
-(defvar bookmark-make-cell-function)
+(defvar bookmark-make-record-function)
 
 ;;;###autoload
 (defun image-mode ()
@@ -290,8 +290,8 @@ to toggle between display as an image and display as text."
   (setq mode-name "Image[text]")
   (setq major-mode 'image-mode)
   ;; Use our own bookmarking function for images.
-  (set (make-local-variable 'bookmark-make-cell-function)
-       'image-bookmark-make-cell)
+  (set (make-local-variable 'bookmark-make-record-function)
+       'image-bookmark-make-record)
 
   ;; Keep track of [vh]scroll when switching buffers
   (image-mode-setup-winprops)
@@ -431,7 +431,7 @@ and showing the image as an image."
 
 ;;; Support for bookmark.el
 
-(defun image-bookmark-make-cell (annotation &rest args)
+(defun image-bookmark-make-record (annotation &rest args)
   (let ((the-record
          `((filename   . ,(buffer-file-name))
            (image-type . ,image-type)
@@ -454,7 +454,7 @@ 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.
+  ;; returned by `bookmark-make-record-function', which see.
   (save-window-excursion
     (let ((filename (bookmark-get-filename bmk))
           (type (cdr (assq 'image-type (bookmark-get-bookmark-record bmk))))
diff --git a/lisp/info.el b/lisp/info.el
index d85c0df8b17..4fc63035dc6 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -3374,7 +3374,7 @@ With a zero prefix arg, put the name inside a function call to `info'."
 (put 'Info-mode 'no-clone-indirect t)
 
 (defvar tool-bar-map)
-(defvar bookmark-make-cell-function)
+(defvar bookmark-make-record-function)
 
 ;; Autoload cookie needed by desktop.el
 ;;;###autoload
@@ -3487,8 +3487,8 @@ Advanced commands:
   (set (make-local-variable 'revert-buffer-function)
        'Info-revert-buffer-function)
   (Info-set-mode-line)
-  (set (make-local-variable 'bookmark-make-cell-function)
-       'Info-bookmark-make-cell)
+  (set (make-local-variable 'bookmark-make-record-function)
+       'Info-bookmark-make-record)
   (run-mode-hooks 'Info-mode-hook))
 
 ;; When an Info buffer is killed, make sure the associated tags buffer
@@ -4326,7 +4326,7 @@ BUFFER is the buffer speedbar is requesting buttons for."
 ;; This is only called from bookmark.el.
 (declare-function bookmark-buffer-file-name "bookmark" ())
 
-(defun Info-bookmark-make-cell (annotation &rest args)
+(defun Info-bookmark-make-record (annotation &rest args)
   (let ((the-record
          `((filename . ,(bookmark-buffer-file-name))
            (front-context-string
@@ -4368,7 +4368,7 @@ BUFFER is the buffer speedbar is requesting buttons for."
 ;;;###autoload
 (defun Info-bookmark-jump (bmk)
   ;; This implements the `handler' function interface for record type returned
-  ;; by `Info-make-cell-function', which see.
+  ;; by `Info-bookmark-make-record', which see.
   (let* ((file (expand-file-name (bookmark-get-filename bmk)))
          (forward-str            (bookmark-get-front-context-string bmk))
          (behind-str             (bookmark-get-rear-context-string bmk))