Re: [feature request] A new cookie type [!] showing the last note taken

[Ihor Radchenko <yantar92@gmail.com>]

> I wouldn't dismiss plain text insertion too easily, either. It also
> includes external tools. What happens if an external tool automatically
> insert notes?
>
> The feature you are requesting could make sense if notes had a clear
> syntax. This would bring some interesting features, too (e.g., being
> able to list all notes in an entry, accurately). But it would also raise
> new problems, as any syntax change (backward compatibility with old
> documents, external tools...). 

I would not call defining syntax for notes "a syntax change". Rather
addition to syntax. Since there was no formal definition of notes in the
past, introducing formal syntax for notes should not break any existing
tool. If anything, it should make it easier for those tools to deal with
notes.

For the compatibility, we can reuse the frequently used (at least,
because it is built-in) syntax used by `org-add-note' (see below).


> This is more realistic, but you are then binding the tool
> (`org-add-note') to the syntax ("[!]"), which is a step in the wrong
> direction. We must not assume Org mode is the only tool writing Org
> documents.

Good point.

Instead of linking to the function, we can define the format used by
`org-add-note' as a formal format for notes. Currently `org-add-note'
uses the following format:

- <note heading> \\
  <User note, possibly multi-line>

The <note heading> is taken from `org-log-note-headings'.

Notably, this syntax is partially used in org, despite lack of formal
definition. For example, `org-habit-parse-todo' assumes that state
change notes were added by `org-add-note' using format defined in
`org-log-note-headings'. All the external tools dealing with state
change statistics already have to consider this syntax.

Also, it can nicely play with the existing built-in
`org-element-plain-list-parser' with note being a special kind of list
element.

Best,
Ihor

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Ihor Radchenko <yantar92@gmail.com> writes:
>
>> I feel that my understand of "note" in context of org is different from
>> yours. Is there a formal definition of "note" in org?
>
> As I stated in my first post a few hours ago:
>
>    Notes are mostly free-form; there is no syntax describing them.
>
>> However, we can formalise the "last note taken" to "last note taken
>> using org-add-note".
>
> This is more realistic, but you are then binding the tool
> (`org-add-note') to the syntax ("[!]"), which is a step in the wrong
> direction. We must not assume Org mode is the only tool writing Org
> documents.
>
>> org-add-note is the only way I am aware about (except plain text,
>> indeed). That's why I wrote the function saving the last note taken
>> using org-add-note into SUMMARY. The property is only used here for
>> convenient retrieval, not because I implied showing a property value.
>
> I understand the property was used for convenience, but showing its
> value is the only problem your can really claim solving at the moment.
>
>> May I know what are the other ways to add note via interactive function
>> in Org?
>
> Capture is certainly one way. In fact, `org-add-note' could (should ?)
> be rewritten using Capture library.
>
> I wouldn't dismiss plain text insertion too easily, either. It also
> includes external tools. What happens if an external tool automatically
> insert notes?
>
> The feature you are requesting could make sense if notes had a clear
> syntax. This would bring some interesting features, too (e.g., being
> able to list all notes in an entry, accurately). But it would also raise
> new problems, as any syntax change (backward compatibility with old
> documents, external tools...). 
>
> Regards,