bookmark structure

bookmark structure

[Drew Adams]

The doc string of bookmark-alist says each entry has this form:
 
(NAME
  (filename . FILE)
  (front-context-string . FRONT-STR)
  (rear-context-string  . REAR-STR)
  (position . POS)
  (info-node . POS)
  (annotation . ANNOTATION))
 
There should not be two occurrences of POS, unless they always have
the same value. The doc string says that info-node is optional, but it
doesn't say that annotation is optional. And the syntax description
doesn't reflect the fact that these are optional (no brackets).
 
The comments in the code, on the other hand, say that this is the(new)
structure:
 
;;        (bookmark-name ((filename . FILENAME)
;;                        (front-context-string . string-in-front)
;;                        (rear-context-string  . string-behind)
;;                        (position . POINT)
;;                        (annotation . annotation)
;;                        (whatever   . VALUE)
;;                        ...
;;                        ))
 
bookmark-name, string-in-front, string-behind, and the second
occurrence of annotation here should be uppercase here.
 
Compared to the doc string, there is an additional level of parens
here for the body, info-node is missing, and additional kinds of
entries (whatever . VALUE)..., are acceptable.
 
The two descriptions should be similar.  It seems that neither is
quite correct. The doc string is missing a level of parens, at least.
 

In GNU Emacs 22.2.1 (i386-mingw-nt5.1.2600)
 of 2008-03-26 on RELEASE
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

Re: bookmark structure

[Stefan Monnier]

> The doc string of bookmark-alist says each entry has this form:
> (NAME
>   (filename . FILE)
>   (front-context-string . FRONT-STR)
>   (rear-context-string  . REAR-STR)
>   (position . POS)
>   (info-node . POS)
>   (annotation . ANNOTATION))
 
That's already fixed in the trunk.


        Stefan

RE: bookmark structure

[Drew Adams]

> > The doc string of bookmark-alist says each entry has this form:
> > (NAME
> >   (filename . FILE)
> >   (front-context-string . FRONT-STR)
> >   (rear-context-string  . REAR-STR)
> >   (position . POS)
> >   (info-node . POS)
> >   (annotation . ANNOTATION))
>  
> That's already fixed in the trunk.

Still doesn't look right to me:

 "where each BOOKMARK is typically of the form

 \(NAME
  (\(filename . FILE\)
   \(front-context-string . FRONT-STR\)
   \(rear-context-string  . REAR-STR\)
   \(position . POS\)
   \(annotation . ANNOTATION\)\))

 So the cdr of each bookmark is an alist too."

Aside from the unnecessary \'s (not a problem, but harder to read the code), the
last sentence is misleading (and unnecessary). The cdr of each bookmark is a
singleton list whose element is an alist.

And what I said about the code comment still holds:

> bookmark-name, string-in-front, string-behind, and the second
> occurrence of annotation here should be uppercase here.

Re: bookmark structure

[Stefan Monnier]

> last sentence is misleading (and unnecessary). The cdr of each bookmark is a
> singleton list whose element is an alist.

Actually, the text was right in this case, the example was wrong.

> And what I said about the code comment still holds:

>> bookmark-name, string-in-front, string-behind, and the second
>> occurrence of annotation here should be uppercase here.

Should both be fixed now, thanks,


        Stefan