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

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

[Drew Adams]

emacs -Q
 
I think there is a doc bug regarding the descriptions of the structure
of `bookmark-alist'.
 
From the doc string of `bookmark-alist':
 
 PARAM-ALIST is typically of the form:
 
 ((filename . FILE)
  (front-context-string . FRONT-STR)
  (rear-context-string  . REAR-STR)
  (position . POS)
  (annotation . ANNOTATION)))
 
There is no description of any of these fields. No description of
FILE, FRONT-STR, REAR-STR, POS, or ANNOTATION. Also, the following
entry is missing, and is (increasingly) important for users of this
variable: (handler . HANDLER).
 
There is some explanation of these fields in the library commentary,
but I believe that it is incorrect as regards FRONT-STR and REAR-STR,
which are called STRING-IN-FRONT and STRING-BEHIND in the commentary:
 
;; STRING-IN-FRONT is a string of `bookmark-search-size' chars of
;;  context in front of the point at which the bookmark is set.
;; STRING-BEHIND is the same thing, but after the point.
 
I think this description is backwards.  The code shows that
STRING-IN-FRONT is in fact a string of text that immediatly *follows*
POS, and STRING-BEHIND is in fact a string that immediately *precedes*
POS.
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

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

[Drew Adams]

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.

bug#4195: marked as done (23.1; bookmark-alist and bookmark doc about structure)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 887 bytes --]

Your message dated Sat, 24 Oct 2009 22:11:39 -0400
with message-id <871vksdxyc.fsf@red-bean.com>
and subject line Fix "bookmark-alist and bookmark doc about structure"
has caused the Emacs bug report #4195,
regarding 23.1; bookmark-alist and bookmark doc about structure
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4195: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4195
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 4089 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <bug-gnu-emacs@gnu.org>
Subject: 23.1; bookmark-alist and bookmark doc about structure
Date: Tue, 18 Aug 2009 15:04:20 -0700
Message-ID: <0F11076DFEDB4B95A57521C0A3E07D35@us.oracle.com>

emacs -Q
 
I think there is a doc bug regarding the descriptions of the structure
of `bookmark-alist'.
 
From the doc string of `bookmark-alist':
 
 PARAM-ALIST is typically of the form:
 
 ((filename . FILE)
  (front-context-string . FRONT-STR)
  (rear-context-string  . REAR-STR)
  (position . POS)
  (annotation . ANNOTATION)))
 
There is no description of any of these fields. No description of
FILE, FRONT-STR, REAR-STR, POS, or ANNOTATION. Also, the following
entry is missing, and is (increasingly) important for users of this
variable: (handler . HANDLER).
 
There is some explanation of these fields in the library commentary,
but I believe that it is incorrect as regards FRONT-STR and REAR-STR,
which are called STRING-IN-FRONT and STRING-BEHIND in the commentary:
 
;; STRING-IN-FRONT is a string of `bookmark-search-size' chars of
;;  context in front of the point at which the bookmark is set.
;; STRING-BEHIND is the same thing, but after the point.
 
I think this description is backwards.  The code shows that
STRING-IN-FRONT is in fact a string of text that immediatly *follows*
POS, and STRING-BEHIND is in fact a string that immediately *precedes*
POS.
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 




[-- Attachment #3: Type: message/rfc822, Size: 1654 bytes --]

From: Karl Fogel <kfogel@red-bean.com>
To: 4195-close@emacsbugs.donarmstrong.com
Subject: Fix "bookmark-alist and bookmark doc about structure"
Date: Sat, 24 Oct 2009 22:11:39 -0400
Message-ID: <871vksdxyc.fsf@red-bean.com>

fixed
--

Thanks for the patch, Drew.  I committed it with very few tweaks:

  $ cvs ci -F ../msg bookmark.el ChangeLog
  /sources/emacs/emacs/lisp/bookmark.el,v  <--  bookmark.el
  new revision: 1.138; previous revision: 1.137
  /sources/emacs/emacs/lisp/ChangeLog,v  <--  ChangeLog
  new revision: 1.16507; previous revision: 1.16506
  Mailing notification to emacs-diffs@gnu.org... sent.
  $