Difference between vulpea-select-describe-fn and vulpea-select-annotate-fn

[Cletip]

Hi! :)
This is a question, so it's not really an issue. So I put it in discussion.

I wanted to know what is the use of two variables, or rather the difference between "annotating" a note and "describing" a note.

Edit : I may have a clue: it is to differentiate two notes that have the same title, but not necessarily the same alias tags etc?

Thanks in advance for your answer.

[d12frosted]

👋 @Cletip

What you see in the completion is just concatenation of strings you get from vulpea-select-describe-fn and vulpea-select-annotate-fn. I decided to introduce two different functions just for convenience of face usage, so that users don't need to deal with that. The result of vulpea-select-describe-fn is applied default face, and the result of vulpea-select-annotate-fn is applied completions-annotations face:

vulpea/vulpea-select.el

Lines 50 to 59 in d2620c8

	(defun vulpea-select-describe (note)
	"Describe a NOTE for completion."
	(propertize
	(concat
	(funcall vulpea-select-describe-fn note)
	(propertize
	(funcall vulpea-select-annotate-fn note)
	'face 'completions-annotations))
	'vulpea-note-id
	(vulpea-note-id note)))

But it's up to user to decide what information to display (and make searchable), either using default face or annotation face. The default format provided by vulpea is TITLE[ (PRIMARY_TITLE)][ #SPACE_SEPARATED_TAGS]:

In the example below, Fransdurif is an alias for Palomino Fino, and the note is tagged as wine and grape.

it is to differentiate two notes that have the same title, but not necessarily the same alias tags etc?

It might help in this situation as well, yes. But really it's up to user to decide what to put there.

Hope that helps.

[Cletip]

Yes, it seems very clear: it is a difference of face, and it is up to each one to choose what he wants to display. So it's for "aesthetic" purposes.

That's very cool, thanks :)

[Cletip]

Side question:

I see in your notes you put the date in the title (2018).
Why didn't you do this: 

• create a "date" metadata
• display the date with the annotation function

This would give this result:

Wouldn't that make more sense? Because for me, the title of the note should not have a date, that is a bit counterintuitive no?
Sorry, it confuses me xD but this is maybe only very subjective.

PS: I had this idea yesterday xD otherwise I would have done exactly like you x)
I'll send my answer to manage the date in a few days, but I'm glad I found this famous annotation function before :)

[d12frosted]

I see in your notes you put the date in the title (2018).

It's not really a date. It's vintage of the wine. For example, I have 3 different vintages of Le Petit Buisson in my notes:

In order to distinguish between them, I generate this title from metadata.

The other note with date is my review of this wine. Again, in order to distinguish between wine and different reviews I generate the title that includes full name of the wine + date of review. Again, all based on metadata 😸

display the date with the annotation function

That's a very good question. It might be a good alternative. For me the answer is quite trivial - historical reasons. Metadata became part of note long after I created existing naming convention. I can easily migrate using a simple util. But I think I will stick to the existing naming convention for the following reasons.

(1) I prefer to have generic annotation, that doesn't have too much indirection. I don't use dates normally, only for reviews.
(2) I need to distinguish between various reviews of the same wine entry in other contexts as well, for example, in org mode buffers:

Because for me, the title of the note should not have a date, that is a bit counterintuitive no?

In general case yes. But in this particular case IMO it's more intuitive to have the date as part of the title.

PS: I had this idea yesterday xD otherwise I would have done exactly like you x)
I'll send my answer to manage the date in a few days, but I'm glad I found this famous annotation function before :)

😸 I am glad that you did. Enjoy ;)

[Cletip]

Huuum, okay, I understand better.
Yes, here the date is perfectly appropriate in the title, because you want to recognize right away when you did the review.

Thanks for the details :)

[d12frosted]

@Cletip no worries. It's nice to discuss various approaches 💪