From unknown Sat Aug 09 13:17:04 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#4195: 23.1; bookmark-alist and bookmark doc about structure Reply-To: "Drew Adams" , 4195@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs 2Resent-Date: Thu, 20 Aug 2009 20:06:49 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: report 4195 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by submit@emacsbugs.donarmstrong.com id=B.125063307125093 (code B ref -1); Thu, 20 Aug 2009 20:06:49 +0000 Received: (at submit) by emacsbugs.donarmstrong.com; 18 Aug 2009 22:04:31 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.5 required=4.0 tests=AWL,FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n7IM4UXl025084 for ; Tue, 18 Aug 2009 15:04:31 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MdWn7-0005Wc-Kx for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:29 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MdWn3-0005WQ-9j for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:29 -0400 Received: from [199.232.76.173] (port=52322 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MdWn3-0005WN-70 for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:25 -0400 Received: from acsinet12.oracle.com ([141.146.126.234]:51648) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MdWn2-0006B4-Gp for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:24 -0400 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n7IM3o07007368 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 18 Aug 2009 22:03:51 GMT Received: from abhmt014.oracle.com (abhmt014.oracle.com [141.146.116.23]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n7IM52Kt022936 for ; Tue, 18 Aug 2009 22:05:02 GMT Received: from dradamslap1 (/141.144.88.50) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 18 Aug 2009 15:04:18 -0700 From: "Drew Adams" To: Date: Tue, 18 Aug 2009 15:04:20 -0700 Message-ID: <0F11076DFEDB4B95A57521C0A3E07D35@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcogT9Za2zDc6jUmRrarWeE8isiymw== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt014.oracle.com [141.146.116.23] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4A8B2563.00CB:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) 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)' From unknown Sat Aug 09 13:17:04 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#4195: 23.1; bookmark-alist and bookmark doc about structure Reply-To: "Drew Adams" , 4195@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs 2Resent-Date: Wed, 26 Aug 2009 04:25:05 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 4195 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by submit@emacsbugs.donarmstrong.com id=B.125126028415718 (code B ref -1); Wed, 26 Aug 2009 04:25:05 +0000 Received: (at submit) by emacsbugs.donarmstrong.com; 26 Aug 2009 04:18:04 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.0 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=unavailable version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n7Q4I2Nh015712 for ; Tue, 25 Aug 2009 21:18:03 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Mg9xR-0007fp-PP for bug-gnu-emacs@gnu.org; Wed, 26 Aug 2009 00:18:01 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Mg9xN-0007f6-Ca for bug-gnu-emacs@gnu.org; Wed, 26 Aug 2009 00:18:01 -0400 Received: from [199.232.76.173] (port=37486 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Mg9xN-0007f3-3q for bug-gnu-emacs@gnu.org; Wed, 26 Aug 2009 00:17:57 -0400 Received: from rcsinet12.oracle.com ([148.87.113.124]:49157 helo=rgminet12.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Mg9xM-0004dc-KO for bug-gnu-emacs@gnu.org; Wed, 26 Aug 2009 00:17:56 -0400 Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by rgminet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n7Q4HaES024491 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 26 Aug 2009 04:17:37 GMT Received: from abhmt015.oracle.com (abhmt015.oracle.com [141.146.116.24]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n7Q4Hggs006237; Wed, 26 Aug 2009 04:17:42 GMT Received: from dradamslap1 (/141.144.168.19) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 25 Aug 2009 20:47:23 -0700 From: "Drew Adams" To: <4195@debbugs.gnu.org>, References: <0F11076DFEDB4B95A57521C0A3E07D35@us.oracle.com> Date: Tue, 25 Aug 2009 20:47:18 -0700 Message-ID: <6731C3160DAE4C42B87EA77BCB11065D@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <0F11076DFEDB4B95A57521C0A3E07D35@us.oracle.com> Thread-Index: AcogT9Za2zDc6jUmRrarWeE8isiymwFq7vZA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt015.oracle.com [141.146.116.24] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.4A94B766.01AB:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) 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. From unknown Sat Aug 09 13:17:04 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#4195: bookmark-alist and bookmark doc about structure Reply-To: Karl Fogel , 4195@debbugs.gnu.org Resent-From: Karl Fogel Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs 2Resent-Date: Tue, 06 Oct 2009 03:45:08 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 4195 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 4195-submit@emacsbugs.donarmstrong.com id=B4195.12548003733265 (code B ref 4195); Tue, 06 Oct 2009 03:45:08 +0000 Received: (at 4195) by emacsbugs.donarmstrong.com; 6 Oct 2009 03:39:33 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=0.1 required=4.0 tests=AWL autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from sanpietro.red-bean.com (Debian-exim@sanpietro.red-bean.com [66.146.206.141]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n963dWUD003258 for <4195@emacsbugs.donarmstrong.com>; Mon, 5 Oct 2009 20:39:33 -0700 Received: from localhost ([127.0.0.1]:35374 helo=floss ident=kfogel) by sanpietro.red-bean.com with esmtp (Exim 4.69) (envelope-from ) id 1Mv0tf-0005gu-Ex for 4195@emacsbugs.donarmstrong.com; Mon, 05 Oct 2009 22:39:31 -0500 From: Karl Fogel To: 4195@debbugs.gnu.org Date: Mon, 05 Oct 2009 23:39:31 -0400 Message-ID: <87tyydi424.fsf@red-bean.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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 From unknown Sat Aug 09 13:17:04 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#4195: bookmark-alist and bookmark doc about structure Reply-To: "Drew Adams" , 4195@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs 2Resent-Date: Tue, 06 Oct 2009 06:50:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 4195 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 4195-submit@emacsbugs.donarmstrong.com id=B4195.125481141131640 (code B ref 4195); Tue, 06 Oct 2009 06:50:04 +0000 Received: (at 4195) by emacsbugs.donarmstrong.com; 6 Oct 2009 06:43:31 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.9 required=4.0 tests=AWL,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet11.oracle.com (acsinet11.oracle.com [141.146.126.233]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n966hUpB031632 for <4195@emacsbugs.donarmstrong.com>; Mon, 5 Oct 2009 23:43:31 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n966hXUd005363 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 6 Oct 2009 06:43:34 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n950KHsU026636; Tue, 6 Oct 2009 06:44:10 GMT Received: from abhmt004.oracle.com by acsmt356.oracle.com with ESMTP id 20224791501254811394; Mon, 05 Oct 2009 23:43:14 -0700 Received: from dradamslap1 (/141.144.168.183) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 05 Oct 2009 23:43:14 -0700 From: "Drew Adams" To: "'Karl Fogel'" , <4195@debbugs.gnu.org> References: <87tyydi424.fsf@red-bean.com> Date: Mon, 5 Oct 2009 23:43:34 -0700 Message-ID: <764E977B5C464F48851D094BDD11CE6E@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcpGN7eLk6VvUhr7RsO9vxeOPVAFJQAF4Ryg In-reply-to: <87tyydi424.fsf@red-bean.com> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt356.oracle.com [141.146.40.156] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.4ACAE709.01BE:SCFMA4539814,ss=1,fgs=0 > 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 From unknown Sat Aug 09 13:17:04 2025 X-Loop: owner@emacsbugs.donarmstrong.com Subject: bug#4195: bookmark-alist and bookmark doc about structure Reply-To: "Drew Adams" , 4195@debbugs.gnu.org Resent-From: "Drew Adams" Resent-To: bug-submit-list@lists.donarmstrong.com Resent-CC: Emacs Bugs 2Resent-Date: Sat, 10 Oct 2009 19:40:06 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-Emacs-PR-Message: followup 4195 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Received: via spool by 4195-submit@emacsbugs.donarmstrong.com id=B4195.125520324614230 (code B ref 4195); Sat, 10 Oct 2009 19:40:06 +0000 Received: (at 4195) by emacsbugs.donarmstrong.com; 10 Oct 2009 19:34:06 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.1 required=4.0 tests=AWL,HAS_BUG_NUMBER, MIME_QP_LONG_LINE,MURPHY_DRUGS_REL8,NEXTPART autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from rgminet11.oracle.com (rcsinet11.oracle.com [148.87.113.123]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n9AJY46U014222 for <4195@emacsbugs.donarmstrong.com>; Sat, 10 Oct 2009 12:34:06 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n9AJZ9NA010846 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 10 Oct 2009 19:35:11 GMT Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n9AFbXki029688; Sat, 10 Oct 2009 19:34:50 GMT Received: from abhmt015.oracle.com by acsmt358.oracle.com with ESMTP id 20330547611255203183; Sat, 10 Oct 2009 14:33:03 -0500 Received: from dradamslap1 (/24.5.184.158) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 10 Oct 2009 12:33:02 -0700 From: "Drew Adams" To: "'Karl Fogel'" , <4195@debbugs.gnu.org> References: <87tyydi424.fsf@red-bean.com> Date: Sat, 10 Oct 2009 12:33:11 -0700 Message-ID: <1764BDF2BF494B78AEFC920F0387FBE8@us.oracle.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_NextPart_000_0018_01CA49A5.D4D2D9A0" X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcpGN7eLk6VvUhr7RsO9vxeOPVAFJQDp2rjg In-Reply-To: <87tyydi424.fsf@red-bean.com> X-MIMEOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt355.oracle.com [141.146.40.155] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090202.4AD0E1A3.014D:SCFMA4539814,ss=1,fgs=0 This is a multi-part message in MIME format. ------=_NextPart_000_0018_01CA49A5.D4D2D9A0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit > 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 ------=_NextPart_000_0018_01CA49A5.D4D2D9A0 Content-Type: application/octet-stream; name="bookmark-2009-10-10.patch" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="bookmark-2009-10-10.patch" diff -cw "bookmark-CVS-2009-10-10.el" "bookmark-patched-2009-10-10.el"=0A= *** bookmark-CVS-2009-10-10.el Sat Oct 10 10:51:36 2009=0A= --- bookmark-patched-2009-10-10.el Sat Oct 10 12:22:10 2009=0A= ***************=0A= *** 252,282 ****=0A= ;;; Core variables and data structures:=0A= (defvar bookmark-alist ()=0A= "Association list of bookmarks and their records.=0A= ! You probably don't want to change the value of this alist yourself;=0A= ! instead, let the various bookmark functions do it for you.=0A= =0A= ! The format of the alist is=0A= =0A= ! \(BOOKMARK1 BOOKMARK2 ...\)=0A= =0A= ! where each BOOKMARK is of the form=0A= =0A= ! (NAME PARAM-ALIST) or (NAME . PARAM-ALIST)=0A= =0A= ! where the first form is the old deprecated one and the second is=0A= ! the new favored one. PARAM-ALIST is typically of the form:=0A= =0A= ! ((filename . FILE)=0A= ! (front-context-string . FRONT-STR)=0A= ! (rear-context-string . REAR-STR)=0A= (position . POS)=0A= ! (handler . HANDLER-FUNC)=0A= ! (annotation . ANNOTATION))=0A= ! =0A= ! If the element `(handler . HANDLER-FUNC)' is present, HANDLER-FUNC=0A= ! will be used to open this bookmark instead of = `bookmark-default-handler',=0A= ! whose calling discipline HANDLER-FUNC should of course match.")=0A= ! =0A= =0A= (defvar bookmarks-already-loaded nil)=0A= =0A= --- 252,290 ----=0A= ;;; Core variables and data structures:=0A= (defvar bookmark-alist ()=0A= "Association list of bookmarks and their records.=0A= ! Bookmark functions update the value automatically.=0A= ! You probably do NOT want to change the value yourself.=0A= =0A= ! The value is an alist with entries of the form=0A= =0A= ! (BOOKMARK-NAME . PARAM-ALIST)=0A= =0A= ! or the deprecated form (BOOKMARK-NAME PARAM-ALIST).=0A= =0A= ! BOOKMARK-NAME is the name you gave to the bookmark when creating it.=0A= =0A= ! PARAM-ALIST is an alist of bookmark information. The order of the=0A= ! entries in PARAM-ALIST is not important. The possible entries are=0A= ! described below. An entry with a key but null value means the entry=0A= ! is not used.=0A= =0A= ! (filename . FILENAME)=0A= (position . POS)=0A= ! (front-context-string . STR-AFTER-POS)=0A= ! (rear-context-string . STR-BEFORE-POS)=0A= ! (handler . HANDLER)=0A= ! (annotation . ANNOTATION)=0A= ! =0A= ! FILENAME names the bookmarked file.=0A= ! POS is the bookmarked buffer position (position in the file).=0A= ! STR-AFTER-POS is buffer text that immediately follows POS.=0A= ! STR-BEFORE-POS is buffer text that immediately precedes POS.=0A= ! ANNOTATION is a string that describes the bookmark.=0A= ! See options `bookmark-use-annotations' and=0A= ! `bookmark-automatically-show-annotations'.=0A= ! HANDLER is a function that provides the bookmark-jump behavior for a=0A= ! specific kind of bookmark. This is the case for Info bookmarks,=0A= ! for instance. HANDLER must accept a bookmark as argument.")=0A= =0A= (defvar bookmarks-already-loaded nil)=0A= =0A= ***************=0A= *** 556,572 ****=0A= =0C=0A= ;;; File format stuff=0A= =0A= ! ;; The OLD format of the bookmark-alist was:=0A= ;;=0A= ! ;; ((BOOKMARK-NAME . (FILENAME=0A= ;; STRING-IN-FRONT=0A= ;; STRING-BEHIND=0A= ;; POINT))=0A= ;; ...)=0A= ;;=0A= ! ;; The NEW format of the bookmark-alist is:=0A= ;;=0A= ! ;; ((BOOKMARK-NAME (filename . FILENAME)=0A= ;; (front-context-string . STRING-IN-FRONT)=0A= ;; (rear-context-string . STRING-BEHIND)=0A= ;; (position . POINT)=0A= --- 564,588 ----=0A= =0C=0A= ;;; File format stuff=0A= =0A= ! ;; *THIS INFORMATION IS IMPORTANT* if you are manipulating bookmark=0A= ! ;; structure or thinking about modifying (redefining) it - please=0A= ! ;; don't.=0A= ! ;;=0A= ! ;; The format of `bookmark-alist' has changed twice in its lifetime.=0A= ! ;; This comment describes the three formats, FIRST, SECOND, and=0A= ! ;; CURRENT.=0A= ! ;;=0A= ! ;; The FIRST format was used prior to Emacs 20:=0A= ;;=0A= ! ;; ((BOOKMARK-NAME (FILENAME=0A= ;; STRING-IN-FRONT=0A= ;; STRING-BEHIND=0A= ;; POINT))=0A= ;; ...)=0A= ;;=0A= ! ;; The SECOND format was introduced in Emacs 20:=0A= ;;=0A= ! ;; ((BOOKMARK-NAME ((filename . FILENAME)=0A= ;; (front-context-string . STRING-IN-FRONT)=0A= ;; (rear-context-string . STRING-BEHIND)=0A= ;; (position . POINT)=0A= ***************=0A= *** 576,606 ****=0A= ;; ))=0A= ;; ...)=0A= ;;=0A= ;;=0A= ! ;; I switched to using an internal as well as external alist because I=0A= ! ;; felt that would be a more flexible framework in which to add=0A= ! ;; features. It means that the order in which values appear doesn't=0A= ! ;; matter, and it means that arbitrary values can be added without=0A= ! ;; risk of interfering with existing ones.=0A= ;;=0A= ! ;; BOOKMARK-NAME is the string the user gives the bookmark and=0A= ! ;; accesses it by from then on.=0A= ;;=0A= ! ;; FILENAME is the location of the file in which the bookmark is set.=0A= ;;=0A= ! ;; STRING-IN-FRONT is a string of `bookmark-search-size' chars of=0A= ! ;; context in front of the point at which the bookmark is set.=0A= ;;=0A= ! ;; STRING-BEHIND is the same thing, but after the point.=0A= ;;=0A= ! ;; The context strings exist so that modifications to a file don't=0A= ! ;; necessarily cause a bookmark's position to be invalidated.=0A= ! ;; bookmark-jump will search for STRING-BEHIND and STRING-IN-FRONT in=0A= ! ;; case the file has changed since the bookmark was set. It will=0A= ! ;; attempt to place the user before the changes, if there were any.=0A= ! ;; ANNOTATION is the annotation for the bookmark; it may not exist=0A= ! ;; (for backward compatibility), be nil (no annotation), or be a=0A= ! ;; string.=0A= =0A= =0A= (defconst bookmark-file-format-version 1=0A= --- 592,633 ----=0A= ;; ))=0A= ;; ...)=0A= ;;=0A= + ;; The CURRENT format was introduced in Emacs 22:=0A= ;;=0A= ! ;; ((BOOKMARK-NAME (filename . FILENAME)=0A= ! ;; (front-context-string . STRING-IN-FRONT)=0A= ! ;; (rear-context-string . STRING-BEHIND)=0A= ! ;; (position . POINT)=0A= ! ;; (annotation . ANNOTATION)=0A= ! ;; (whatever . VALUE)=0A= ! ;; ...=0A= ! ;; ))=0A= ! ;; ...)=0A= ;;=0A= ! ;; Both FIRST and SECOND have the same level of nesting: the cadr of a=0A= ! ;; bookmark record is a list of entry information. FIRST and SECOND=0A= ! ;; differ in the form of the record information: FIRST uses a list of=0A= ! ;; atoms, and SECOND uses an alist. In the FIRST format, the order of=0A= ! ;; the list elements matters. In the SECOND format, the order of the=0A= ! ;; alist elements is unimportant. The SECOND format facilitates the=0A= ! ;; addition of new kinds of elements, to support new kinds of=0A= ! ;; bookmarks or code evolution.=0A= ;;=0A= ! ;; The CURRENT format removes a level of nesting wrt FIRST and SECOND,=0A= ! ;; saving one cons cell per bookmark: the cadr of a bookmark record is=0A= ! ;; no longer a cons. Why that change was made remains a mystery -=0A= ! ;; just be aware of it. (Be aware too that this explanatory comment=0A= ! ;; was incorrect in Emacs 22 and Emacs 23.1.)=0A= ;;=0A= ! ;; To deal with the change from FIRST format to SECOND, conversion=0A= ! ;; code was added, and it is still in use - see=0A= ! ;; `bookmark-maybe-upgrade-file-format'.=0A= ;;=0A= ! ;; No conversion from SECOND to CURRENT is done. Instead, the code=0A= ! ;; handles both formats OK. It must continue to do so.=0A= ;;=0A= ! ;; See the doc string of `bookmark-alist' for information about the=0A= ! ;; elements that define a bookmark (e.g. `filename').=0A= =0A= =0A= (defconst bookmark-file-format-version 1=0A= ***************=0A= *** 736,760 ****=0A= "Set a bookmark named NAME at the current location.=0A= If name is nil, then prompt the user.=0A= =0A= ! With prefix arg (NO-OVERWRITE), do not overwrite a bookmark that=0A= ! has the same name as NAME if such a bookmark already exists, but=0A= ! instead push the new bookmark onto the bookmark alist. Thus the=0A= ! most recently set bookmark with name NAME would be the one in=0A= ! effect at any given time, but the others are still there, should=0A= ! the user decide to delete the most recent one.=0A= =0A= To yank words from the text of the buffer and use them as part of the=0A= bookmark name, type C-w while setting a bookmark. Successive C-w's=0A= yank successive words.=0A= =0A= ! Typing C-u will insert (at the bookmark name prompt) the name of the=0A= ! last bookmark used in the document where the new bookmark is being set;=0A= ! this helps one use a single bookmark name to track progress through=0A= ! a large document. If there is no prior bookmark for this document,=0A= ! then C-u inserts an appropriate name based on the buffer or file.=0A= =0A= ! Use \\[bookmark-delete] to remove bookmarks \(give it a name and it=0A= ! removes only the first instance of a bookmark with that name from=0A= the list of bookmarks.\)"=0A= (interactive (list nil current-prefix-arg))=0A= (let* ((record (bookmark-make-record))=0A= --- 763,787 ----=0A= "Set a bookmark named NAME at the current location.=0A= If name is nil, then prompt the user.=0A= =0A= ! With a prefix arg (non-nil NO-OVERWRITE), do not overwrite any=0A= ! existing bookmark that has the same name as NAME, but instead push the=0A= ! new bookmark onto the bookmark alist. The most recently set bookmark=0A= ! with name NAME is thus the one in effect at any given time, but the=0A= ! others are still there, should the user decide to delete the most=0A= ! recent one.=0A= =0A= To yank words from the text of the buffer and use them as part of the=0A= bookmark name, type C-w while setting a bookmark. Successive C-w's=0A= yank successive words.=0A= =0A= ! Typing C-u inserts (at the bookmark name prompt) the name of the last=0A= ! bookmark used in the document where the new bookmark is being set;=0A= ! this helps you use a single bookmark name to track progress through a=0A= ! large document. If there is no prior bookmark for this document, then=0A= ! C-u inserts an appropriate name based on the buffer or file.=0A= =0A= ! Use \\[bookmark-delete] to remove bookmarks \(you give it a name and=0A= ! it removes only the first instance of a bookmark with that name from=0A= the list of bookmarks.\)"=0A= (interactive (list nil current-prefix-arg))=0A= (let* ((record (bookmark-make-record))=0A= ***************=0A= *** 884,891 ****=0A= =0A= =0A= (defun bookmark-buffer-name ()=0A= ! "Return the name of the current buffer (or its file, if any) in a=0A= ! way that is suitable as a bookmark name."=0A= (cond=0A= ;; Or are we a file?=0A= (buffer-file-name (file-name-nondirectory buffer-file-name))=0A= --- 911,918 ----=0A= =0A= =0A= (defun bookmark-buffer-name ()=0A= ! "Return the name of the current buffer in a form usable as a = bookmark name.=0A= ! If the buffer is associated with a file or directory, use that name."=0A= (cond=0A= ;; Or are we a file?=0A= (buffer-file-name (file-name-nondirectory buffer-file-name))=0A= ***************=0A= *** 906,913 ****=0A= =0A= =0A= (defun bookmark-yank-word ()=0A= ! "Get the next word from the buffer and append it to the name of the=0A= ! bookmark currently being set, advancing point by one word."=0A= (interactive)=0A= (let ((string (with-current-buffer bookmark-current-buffer=0A= (goto-char bookmark-yank-point)=0A= --- 933,939 ----=0A= =0A= =0A= (defun bookmark-yank-word ()=0A= ! "Insert the next word from the bookmarked buffer into the current = buffer."=0A= (interactive)=0A= (let ((string (with-current-buffer bookmark-current-buffer=0A= (goto-char bookmark-yank-point)=0A= ***************=0A= *** 1005,1012 ****=0A= the latter is usually only used by programmatic callers.=0A= =0A= If DISPLAY-FUNC is non-nil, it is a function to invoke to display the=0A= ! bookmark. It defaults to `switch-to-buffer'; a typical other value=0A= ! would be, e.g., `switch-to-buffer-other-window'."=0A= (interactive=0A= (list (bookmark-completing-read "Jump to bookmark"=0A= bookmark-current-bookmark)))=0A= --- 1031,1038 ----=0A= the latter is usually only used by programmatic callers.=0A= =0A= If DISPLAY-FUNC is non-nil, it is a function to invoke to display the=0A= ! bookmark. It defaults to `switch-to-buffer'. A typical value for=0A= ! DISPLAY-FUNCC would be `switch-to-buffer-other-window'."=0A= (interactive=0A= (list (bookmark-completing-read "Jump to bookmark"=0A= bookmark-current-bookmark)))=0A= ***************=0A= *** 1046,1053 ****=0A= Changes current buffer and point and returns nil, or signals a = `file-error'.=0A= =0A= If BOOKMARK has no file, this is a no-op. If BOOKMARK has a file, but=0A= ! that file no longer exists, then offer interactively to relocate = BOOKMARK.=0A= ! "=0A= (condition-case err=0A= (funcall (or (bookmark-get-handler bookmark)=0A= 'bookmark-default-handler)=0A= --- 1072,1078 ----=0A= Changes current buffer and point and returns nil, or signals a = `file-error'.=0A= =0A= If BOOKMARK has no file, this is a no-op. If BOOKMARK has a file, but=0A= ! that file no longer exists, then offer interactively to relocate = BOOKMARK."=0A= (condition-case err=0A= (funcall (or (bookmark-get-handler bookmark)=0A= 'bookmark-default-handler)=0A= ***************=0A= *** 1362,1369 ****=0A= =0A= =0A= (defun bookmark-import-new-list (new-list)=0A= ! "Add NEW-LIST of bookmarks to `bookmark-alist', rename new bookmarks=0A= ! with \"\" extensions where they collide with existing bookmark = names."=0A= (let ((lst new-list)=0A= (names (bookmark-all-names)))=0A= (while lst=0A= --- 1387,1395 ----=0A= =0A= =0A= (defun bookmark-import-new-list (new-list)=0A= ! "Add NEW-LIST of bookmarks to `bookmark-alist'.=0A= ! Rename new bookmarks as needed using suffix \"\" (N=3D1,2,3...), = when=0A= ! they conflict with existing bookmark names."=0A= (let ((lst new-list)=0A= (names (bookmark-all-names)))=0A= (while lst=0A= ***************=0A= *** 1375,1382 ****=0A= =0A= =0A= (defun bookmark-maybe-rename (full-record names)=0A= ! "If bookmark record FULL-RECORD collides with anything in NAMES, give=0A= ! FULL-RECORD a new name. This is a helper for = `bookmark-import-new-list'."=0A= (let ((found-name (bookmark-name-from-full-record full-record)))=0A= (if (member found-name names)=0A= ;; We've got a conflict, so generate a new name=0A= --- 1401,1408 ----=0A= =0A= =0A= (defun bookmark-maybe-rename (full-record names)=0A= ! "Rename bookmark FULL-RECORD if its current name is already used.=0A= ! This is a helper for `bookmark-import-new-list'."=0A= (let ((found-name (bookmark-name-from-full-record full-record)))=0A= (if (member found-name names)=0A= ;; We've got a conflict, so generate a new name=0A= ***************=0A= *** 1634,1642 ****=0A= =0A= (defun bookmark-bmenu-show-filenames (&optional force)=0A= "In an interactive bookmark list, show filenames along with = bookmarks.=0A= ! =0A= ! If FORCE is non-nil, force a redisplay showing the filenames; this is=0A= ! used mainly for debugging, and should not be necessary in normal = usage."=0A= (if (and (not force) bookmark-bmenu-toggle-filenames)=0A= nil ;already shown, so do nothing=0A= (save-excursion=0A= --- 1660,1667 ----=0A= =0A= (defun bookmark-bmenu-show-filenames (&optional force)=0A= "In an interactive bookmark list, show file names along with = bookmarks.=0A= ! Non-nil FORCE forces a redisplay showing the filenames. FORCE is used=0A= ! mainly for debugging, and should not be necessary in normal use."=0A= (if (and (not force) bookmark-bmenu-toggle-filenames)=0A= nil ;already shown, so do nothing=0A= (save-excursion=0A= ***************=0A= *** 1664,1672 ****=0A= =0A= (defun bookmark-bmenu-hide-filenames (&optional force)=0A= "In an interactive bookmark list, hide the filenames of the = bookmarks.=0A= ! =0A= ! If FORCE is non-nil, force a redisplay hiding the filenames; this is=0A= ! used mainly for debugging, and should not be necessary in normal = usage."=0A= (if (and (not force) bookmark-bmenu-toggle-filenames)=0A= ;; nothing to hide if above is nil=0A= (save-excursion=0A= --- 1689,1696 ----=0A= =0A= (defun bookmark-bmenu-hide-filenames (&optional force)=0A= "In an interactive bookmark list, hide the filenames of the = bookmarks.=0A= ! Non-nil FORCE forces a redisplay showing the filenames. FORCE is used=0A= ! mainly for debugging, and should not be necessary in normal use."=0A= (if (and (not force) bookmark-bmenu-toggle-filenames)=0A= ;; nothing to hide if above is nil=0A= (save-excursion=0A= ***************=0A= *** 1703,1714 ****=0A= =0A= =0A= (defun bookmark-bmenu-check-position ()=0A= ! "Return non-nil if on a line with a bookmark (the actual value=0A= ! returned is `bookmark-alist'). Else reposition and try again; else if=0A= ! still no bookmark, return nil."=0A= ! ;; FIXME: I don't believe this doc string. As far as I can tell,=0A= ! ;; this function always just returns bookmark-alist. So what is=0A= ! ;; it for, really? -kfogel, 2009-10-04=0A= (cond ((< (count-lines (point-min) (point)) 2)=0A= (goto-char (point-min))=0A= (forward-line 2)=0A= --- 1727,1742 ----=0A= =0A= =0A= (defun bookmark-bmenu-check-position ()=0A= ! "If point is not on a bookmark line, move it to one.=0A= ! If before the first bookmark line, move it to the first.=0A= ! If after the last, move it to the last.=0A= ! Return `bookmark-alist'"=0A= ! ;; FIXME: The doc string originally implied that this returns nil if=0A= ! ;; not on a bookmark, which is false. Is there any real reason to=0A= ! ;; return `bookmark-alist'? This seems to be called in a few places=0A= ! ;; as a check of whether point is on a bookmark line. Those=0A= ! ;; "checks" are in fact no-ops, since this never returns nil.=0A= ! ;; -dadams, 2009-10-10=0A= (cond ((< (count-lines (point-min) (point)) 2)=0A= (goto-char (point-min))=0A= (forward-line 2)=0A= ***************=0A= *** 1722,1728 ****=0A= =0A= (defun bookmark-bmenu-bookmark ()=0A= "Return the bookmark for this line in an interactive bookmark list = buffer."=0A= - ;; return a string which is bookmark of this line.=0A= (if (bookmark-bmenu-check-position)=0A= (save-excursion=0A= (save-window-excursion=0A= --- 1750,1755 ----=0A= =0A= Diff finished at Sat Oct 10 12:23:03=0A= ------=_NextPart_000_0018_01CA49A5.D4D2D9A0-- From unknown Sat Aug 09 13:17:04 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.427 (Entity 5.427) X-Loop: owner@emacsbugs.donarmstrong.com From: help-debbugs@gnu.org (Emacs bug Tracking System) To: "Drew Adams" Subject: bug#4195 closed by Karl Fogel (Fix "bookmark-alist and bookmark doc about structure") Message-ID: References: <871vksdxyc.fsf@red-bean.com> <0F11076DFEDB4B95A57521C0A3E07D35@us.oracle.com> X-Emacs-PR-Message: they-closed 4195 X-Emacs-PR-Package: emacs Reply-To: 4195@debbugs.gnu.org Date: Sun, 25 Oct 2009 02:20:06 +0000 Content-Type: multipart/mixed; boundary="----------=_1256437206-27957-1" This is a multi-part message in MIME format... ------------=_1256437206-27957-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" This is an automatic notification regarding your bug report which was filed against the emacs package: #4195: 23.1; bookmark-alist and bookmark doc about structure It has been closed by Karl Fogel . Their explanation is attached below along with your original report. If this explanation is unsatisfactory and you have not received a better one in a separate message then please contact Karl Fogel by replying to this email. --=20 4195: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D4195 Emacs Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1256437206-27957-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 4195-close) by emacsbugs.donarmstrong.com; 25 Oct 2009 02:11:42 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=0.0 required=4.0 tests=MURPHY_DRUGS_REL8 autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from sanpietro.red-bean.com (Debian-exim@sanpietro.red-bean.com [66.146.206.141]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n9P2BeFo027220 for <4195-close@emacsbugs.donarmstrong.com>; Sat, 24 Oct 2009 19:11:41 -0700 Received: from localhost ([127.0.0.1]:50788 helo=floss ident=kfogel) by sanpietro.red-bean.com with esmtp (Exim 4.69) (envelope-from ) id 1N1sa3-0003NU-Vy for 4195-close@emacsbugs.donarmstrong.com; Sat, 24 Oct 2009 21:11:40 -0500 From: Karl Fogel To: 4195-close@debbugs.gnu.org Subject: Fix "bookmark-alist and bookmark doc about structure" Reply-To: Karl Fogel Date: Sat, 24 Oct 2009 22:11:39 -0400 Message-ID: <871vksdxyc.fsf@red-bean.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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. $ ------------=_1256437206-27957-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by emacsbugs.donarmstrong.com; 18 Aug 2009 22:04:31 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.5 required=4.0 tests=AWL,FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n7IM4UXl025084 for ; Tue, 18 Aug 2009 15:04:31 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MdWn7-0005Wc-Kx for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:29 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MdWn3-0005WQ-9j for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:29 -0400 Received: from [199.232.76.173] (port=52322 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MdWn3-0005WN-70 for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:25 -0400 Received: from acsinet12.oracle.com ([141.146.126.234]:51648) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MdWn2-0006B4-Gp for bug-gnu-emacs@gnu.org; Tue, 18 Aug 2009 18:04:24 -0400 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n7IM3o07007368 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 18 Aug 2009 22:03:51 GMT Received: from abhmt014.oracle.com (abhmt014.oracle.com [141.146.116.23]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n7IM52Kt022936 for ; Tue, 18 Aug 2009 22:05:02 GMT Received: from dradamslap1 (/141.144.88.50) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 18 Aug 2009 15:04:18 -0700 From: "Drew Adams" To: 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> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcogT9Za2zDc6jUmRrarWeE8isiymw== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt014.oracle.com [141.146.116.23] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4A8B2563.00CB:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) 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)' ------------=_1256437206-27957-1--