Bookmark+: automated annotating?

Bookmark+: automated annotating?

[Christopher Howard]

Hi, I've been playing around with bookmark+. As mentioned previously, I want to try using bookmarks annotations as metadata for a few hundred files in one of my projects. On my end, I started working on an emacs script to pull some important documentation data out of the files. I was wondering now if I can tie that into some bookmark or bookmark+ API to automatically annotate the file bookmarks, rather than copying and pasting everything. Could I get a bit of guidance as far as what functions would be worth looking at?

-- 
📛 Christopher Howard
🚀 gemini://gem.librehacker.com
🌐 http://gem.librehacker.com

בראשית ברא אלהים את השמים ואת הארץ

RE: [External] : Bookmark+: automated annotating?

[Drew Adams]

> Hi, I've been playing around with bookmark+. As mentioned previously, I
> want to try using bookmarks annotations as metadata for a few hundred
> files in one of my projects. On my end, I started working on an emacs
> script to pull some important documentation data out of the files. I was
> wondering now if I can tie that into some bookmark or bookmark+ API to
> automatically annotate the file bookmarks, rather than copying and
> pasting everything. Could I get a bit of guidance as far as what
> functions would be worth looking at?

IIUC, you're pulling documentation data out of files,
and you want to use that data as metadata, associated
with but separate from the files it describes.

Does that mean different data for different files, in
general?  I guess so.

The code you write to pull that data out of the files
can also "automatically" place it wherever you like.
I'll assume here that you'll use Emacs Lisp to do that.

Some possibilities making use of bookmarks:

1. A bookmark annotation is, a priori, free-form text -
anything you like.  Function `bookmark-set-annotation'
adds an annotation to a given bookmark, or updates its
existing annotation.  Function `bookmark-get-annotation'
is the corresponding getter.  They use `bookmark-prop-set'
and `bookmark-prop-get'.  The value of bookmark
property/attribute `annotation' is just a string.
They're all you really need to know, to add/update
bookmark annotations.

2. If you don't care about the interactive aspects of
annotating and showing annotations then you can just
store whatever metadata text you like in a different
bookmark attribute of your own choosing.

3. If you use Bookmark+ then the mode for viewing and
editing a bookmark annotation is Org mode by default
(see option `bmkp-annotation-modes-inherit-from').

You can get the effect of using a longer annotation, and
some other advantages, by using an "annotation forward"
in the annotation text.  This is short text that serves
only as a pointer to an external file, URL, or other
bookmark.

For example, you can use bookmarks to one or more Org
files to annotate (provide notes about, or metadata for)
one or more other bookmarks.  This can help not only by
making bookmark data smaller but also for sharing
metadata portions and for refactoring.

Interactively, when you show an annotation that contains
such a pointer, you visit the pointer's destination
instead of seeing the annotation text in the bookmark.

4. You can organize sets of bookmarks, whether wrt
annotation (e.g. organize your metadata) or anything
else, in various ways.  The Bookmark+ doc covers the
possibilities.
____

Dunno whether this is the kind of info you're looking
for.  Your request is somewhat vague.  HTH.

Re: [External] : Bookmark+: automated annotating?

[Christopher Howard]

Drew Adams <drew.adams@oracle.com> writes:

> 1. A bookmark annotation is, a priori, free-form text -
> anything you like.  Function `bookmark-set-annotation'
> adds an annotation to a given bookmark, or updates its
> existing annotation.  Function `bookmark-get-annotation'
> is the corresponding getter.  They use `bookmark-prop-set'
> and `bookmark-prop-get'.  The value of bookmark
> property/attribute `annotation' is just a string.
> They're all you really need to know, to add/update
> bookmark annotations.

Thank you, I think bookmark-set-annotation and bookmark-get-annotation are what I am looking for.

Something I was wondering about is if it was possible to display the annotations in the bookmark list itself, to the right of the bookmark name. Or if that was a feature that had been considered. Of course, only the first line of the annotation would fit there. But I think that would be still be useful, in the use case where the Bookmark name was simply the file name, and the annotation represented some kind of description.

The next best thing, it appears, is to use bookmark-bmenu-show-all-annotations, which gives you the bookmark names and annotations all in one buffer you can scroll through quickly; unfortunately, however, in the *Bookmark Annotations* buffer it is not possible to conveniently navigate through the bookmark names (with a TAB or whatever) or to jump to one with RET.

-- 
Christopher Howard

RE: [External] : Bookmark+: automated annotating?

[Drew Adams]

> I think bookmark-set-annotation and bookmark-get-annotation
> are what I am looking for.

That was my guess.

> Something I was wondering about is if it was possible to display the
> annotations in the bookmark list itself, to the right of the bookmark
> name. Or if that was a feature that had been considered. Of course, only
> the first line of the annotation would fit there. But I think that would
> be still be useful, in the use case where the Bookmark name was simply
> the file name, and the annotation represented some kind of description.

Not at the present.  There are several things that
could be added as columns, and it's not obvious
(to me) whether adding any of them is a good thing
to try.  I've kept adding columns to a minimum.

FYI: If you use only vanilla bookmark.el, not
Bookmark+, it uses `tabulated-list-mode' to
implement the bookmark-list display.  You could
add columns to that display, if you wanted.
I'm not a fan of `tabulated-list-mode' for the
bookmark-list display (a fortiori for Dired) -
too limited.

> The next best thing, it appears, is to use bookmark-bmenu-show-all-
> annotations, which gives you the bookmark names and annotations all in
> one buffer you can scroll through quickly;

Yes.

> unfortunately, however, in the *Bookmark Annotations*
> buffer it is not possible to conveniently navigate
> through the bookmark names (with a TAB or whatever)
> or to jump to one with RET.

Correct.
I haven't made any attempt to modify/enhance
`bookmark-bmenu-show-all-annotations', including
its display.

I don't think a lot of people have really leveraged
the feature of bookmark annotations.  What you have
in mind might be the most that anyone's tried to
take good advantage of it (dunno).