Subject: Re: Fix "Document incompatible change to format of bookmarks"

From: Karl Fogel <[email-masked]>
Date: Fri, 09 Oct 2009 02:59:04 -0400

"Drew Adams" <[email-masked]> writes:
> Thanks for adding the NEWS entry, Karl.
>
> It's really too bad that this incompatible change was made without
> anyone documenting the reason (at least I haven't found such
> documentation). Likewise, without any discussion (that I'm aware of).

I agree.  By the way, I may well be the guilty party -- I've been
hacking intermittently on bookmark.el for sixteen years now, and there
are many changes I've simply forgotten I ever made.  It's quite likely
that when Stefan made rev 1.114, he was just continuing a trend I or
someone else had already started.

> One can only hope that the change was truly necessary or at least somehow
> useful, for whatever unknown reason.

Well, looking at it, I don't think it was really needed.  However, now
that we have made the change, I think we should just stick with it and
make it be The One True Format.  That's why I'm eager to write a truly
robust fix for bug #3646.

> The 1.114 log entry seems to suggest that it only adjusted some parts of the
> code to work with "the 2 slightly different formats used until now in
> bookmark.el's code."

Yup.  I or someone else might have written a bug before then that caused
the nominal format 1 to be written out incorrectly (in what is now the
new format, as-yet-to-be-named "format 2" I guess).

> It's unclear what that text really tries to mean, but if it is
> suggesting that the new, Emacs 23 format was already in use in (some
> parts of) the bookmark code, then that's not true (assuming that
> you're right that 1.114 is the culprit, which it does seem to be).
>
> This is an incompatible change in the basic bookmark format, starting
> with Emacs 23 (apparently, starting with 1.114). It seems to be a
> gratuitous change, but how to tell, since no reason was given?
>
> I wonder if, in making that change, Stefan was aware that the format
> is new, or if he perhaps really thought that it had been in use
> previously. Perhaps he was confused by the misleading (incorrect)
> comments in the file. Dunno. And we'll likely never know, as you point
> out. Too bad.

The out-of-date comments certainly didn't help matters, yeah.

> We've now had at least two incompatible format changes to the `bookmark-alist'
> structure, over its history. Neither of which brought anything useful to the
> party, AFAICT. Oh well. Let's hope that next year someone doesn't mutate the
> structure to a fourth format. ;-)

We're going to document it for real this time, give the new format a
name, make sure the version number gets bumped, and explicitly request
that no one change the format again.  It should be extensible enough as
it is, after all.

Thanks for noticing the problem and taking the time to describe it so
thoroughly; that was a huge help.

-Karl