Subject: bug#4195: 23.1; bookmark-alist and bookmark doc about structure

From: "Drew Adams" <[email-masked]>
Date: Tue, 25 Aug 2009 20:47:18 -0700

In addition to what I said earlier, the doc about the structure in the comments
of the file has an additional problem. It says this (Emacs 23):

;; The OLD format of the bookmark-alist was:
;;
;;       ((BOOKMARK-NAME . (FILENAME
;;                          STRING-IN-FRONT
;;                          STRING-BEHIND
;;                          POINT))
;;        ...)
;;
;; The NEW format of the bookmark-alist is:
;;
;;       ((BOOKMARK-NAME (filename   . FILENAME)
;;                       (front-context-string . STRING-IN-FRONT)
;;                       (rear-context-string  . STRING-BEHIND)
;;                       (position   . POINT)
;;                       (annotation . ANNOTATION)
;;                       (whatever   . VALUE)
;;                       ...
;;                       ))
;;        ...)

This is misleading and incomplete. First, the dot notation in the OLD
description corresponds to just this, which is simpler and parallel to the NEW
description:

((BOOKMARK-NAME FILENAME
                STRING-IN-FRONT
                STRING-BEHIND
                POINT)
 ...)

IOW, the doc can give the incorrect impression (without a careful reading) that
it is contrasting different levels of nesting, because the OLD example uses dot
notation and the NEW does not. This is misleading; there is no difference in
nesting between the two. (The description of OLD is also incorrect - see further
below).

The structure description is also incomplete, and doubly misleading, because the
meaning of OLD and NEW has in fact changed more than once. The same comment, in
Emacs 20 was as follows (Emacs 20):

;; The OLD format of the bookmark-alist was:
;;
;;       ((bookmark-name (filename
;;                        string-in-front
;;                        string-behind
;;                        point))
;;        ...)
;;
;; The NEW format of the bookmark-alist is:
;;
;;       ((bookmark-name ((filename . FILENAME)
;;                        (front-context-string . string-in-front)
;;                        (rear-context-string  . string-behind)
;;                        (position . POINT)
;;                        (annotation . annotation)
;;                        (whatever   . VALUE)
;;                        ...
;;                        ))
;;        ...)

Notice that here both OLD and NEW have an additional level of nesting, compared
with the OLD and NEW of the Emacs 23 comment. That's because in Emacs 20
bookmarks had an additional level of nesting. Again, though, there is no
difference in nesting level between OLD and NEW here.

Finally, the Emacs 23 OLD description is erroneous. The so-called OLD of the
Emacs 23 commentary has never existed, AFAIK. Instead, there was first the OLD
form described in the Emacs 20 comment, then the NEW form described in the Emacs
20 comment, then the NEW form described in the Emacs 23 comment (introduced in
Emacs 22, I think).

I use both Emacs 20 and Emacs 23, and so I have some bookmarks of each of the
forms that those two releases produce, that is, the forms corresponding to NEW
for Emacs 20 and NEW for Emacs 23.

The code handles both of these formats OK. And it probably still handles
(converts) bookmarks of the form corresponding to OLD for Emacs 20, should any
still be around.

Because Emacs-20-OLD bookmarks are still supported (by converting), the Emacs 23
doc needs to describe their structure. For that, it should use the OLD
description from the Emacs 20 doc. Because Emacs-20-NEW bookmarks are also still
supported, the Emacs 23 doc needs to describe their structure also - call it
OLD2. The OLD2 bookmarks are still in use; they are certainly more common than
the Emacs-20-OLD bookmarks.

Currently, neither the Emacs-20-OLD  nor the Emacs-20-NEW forms are described,
and there is a description Emacs-23-OLD of a format that has never even existed.

The doc describing the structure of bookmarks, as this mail and the previous
mail together should make clear, is unclear and incorrect. Both the doc strings
and the code commentary need an overhaul.