GNU bug report logs - #4195
23.1; bookmark-alist and bookmark doc about structure

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4195 in the body.
You can then email your comments to 4195 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

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

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)'
 

Message #10 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <4195 <at> debbugs.gnu.org>, <bug-gnu-emacs <at> gnu.org>
Subject: RE: bug#4195: 23.1; bookmark-alist and bookmark doc about structure
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.

Message #20 received at 4195 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Karl Fogel <kfogel <at> red-bean.com>
To: 4195 <at> debbugs.gnu.org
Subject: Re: bookmark-alist and bookmark doc about structure
Date: Mon, 05 Oct 2009 23:39:31 -0400

Drew, can you have a go at fixing this one?  It looks like you've got
the necessary head state, perhaps more than I do.  I've also got some
other bookmark.el bug reports (3646, 3645, 3375, 1199, 4485, 4296, 4349,
and 4348 -- though note that 3646 may actually get easier after 4195 is
fixed), most of which will require coding, so I'd like to concentrate on
them first.

Fine to say no, obviously :-), but I thought I'd ask.

Thanks,
-Karl

Message #25 received at 4195 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Karl Fogel'" <kfogel <at> red-bean.com>, <4195 <at> debbugs.gnu.org>
Subject: RE: bug#4195: bookmark-alist and bookmark doc about structure
Date: Mon, 5 Oct 2009 23:43:34 -0700

> Drew, can you have a go at fixing this one?  It looks like you've got
> the necessary head state, perhaps more than I do.  I've also got some
> other bookmark.el bug reports (3646, 3645, 3375, 1199, 4485, 
> 4296, 4349, and 4348 -- though note that 3646 may actually get easier 
> after 4195 is fixed), most of which will require coding, so I'd like to 
> concentrate on them first.
> 
> Fine to say no, obviously :-), but I thought I'd ask.

Yes, but not before next weekend. I just don't have the time now.

I'll try to take a look at it before too long, and send you something for
comment. (Yes, 3646 is related to 4195.)

Thanks for your work on these bugs.

 - Drew

Message #30 received at 4195 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Karl Fogel'" <kfogel <at> red-bean.com>, <4195 <at> debbugs.gnu.org>
Subject: RE: bug#4195: bookmark-alist and bookmark doc about structure
Date: Sat, 10 Oct 2009 12:33:11 -0700

[Message part 1 (text/plain, inline)]

> From: Karl Fogel Sent: Monday, October 05, 2009 8:40 PM
> 
> Drew, can you have a go at fixing this one?  It looks like you've got
> the necessary head state, perhaps more than I do.  I've also got some
> other bookmark.el bug reports (3646, 3645, 3375, 1199, 4485, 
> 4296, 4349, and 4348 -- though note that 3646 may actually get easier 
> after 4195 is fixed), most of which will require coding, so I'd like to 
> concentrate on them first.
> Fine to say no, obviously :-), but I thought I'd ask.

Hi Karl,

Attached is a patch against today's CVS file.

I updated the `bookmark-alist' doc string and the large comment about the
various formats and their evolution. I also made some minor changes to other doc
strings (e.g. some first lines that were too long). Please read over what I
wrote and correct it as you see fit. In particular, I'm no expert on the format
changes.

HTH, and thanks for all your work on the bugs.

 - Drew

[bookmark-2009-10-10.patch (application/octet-stream, attachment)]

Message #35 received at 4195-close <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Karl Fogel <kfogel <at> red-bean.com>
To: 4195-close <at> debbugs.gnu.org
Subject: Fix "bookmark-alist and bookmark doc about structure"
Date: Sat, 24 Oct 2009 22:11:39 -0400

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 <at> gnu.org... sent.
  $ 

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.