Subject: 23.1; bookmark-alist and bookmark doc about structure

From: "Drew Adams" <[email-masked]>
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)'