Re: [RFC] DOCT: Declarative Org Capture Templates (easier template syntax)

[No Wayman]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> The fact that we need a tool like "doct" to write templates in a 
> compact
> form may be a sign that the data type is not good enough. 
> Actually it
> sounds like a failure somehow.

Agreed. That's why I wrote doct in the first place.
As others have expressed, there's far too many elements required 
to ask the user to recall what position they fall in.
A plist is better in that the keys describe their values and can 
be specified in any order.
This also makes it easier for people to share templates, because 
they can actually tell what the template is intended to do by 
looking at it.

Another thing that is confusing about "capture templates" is that 
the words "template" and "entry" are overloaded in the 
documentation. From the docstring of org-capture-templates:

> Templates for the creation of new entries.
> Each entry is a list with the following items:

So org-capture-templates is a "list of entries which create new 
entries via templates"?
Confusing for me now, let alone the first time I tried to write my 
own templates.

doct also does more to check the validity of the template's form 
when it is defined.
I prioritized this because the worst time to figure out your 
template is malformed is when you go to capture something in the 
middle of another, unrelated task.

> Should templates definition be more compact out of the box? 
> Could the
> data type be made more powerful to permit more complex templates 
> without
> relying on doct? IOW, can a tool such a doct be made transparent 
> to the
> user?

My initial idea for integrating doct with Org was to just provide 
a user option, e.g. org-capture-use-doct-syntax.
Then the only thing needed would be a conditional in 
org-capture-upgrade-templates which would delegate to doct when 
said user option is non-nil. 
That would allow those who are interested in using the feature to 
opt-in without breaking existing templates. Then as support for 
older syntax is dropped, (if ever? it looks like 
`org-capture-upgrade-templates' dates back to early 2017, and I 
think it makes sense to retain such a path) those features could 
be moved into org-capture.

I'm open to bringing doct's features into Org mode, but I'd prefer 
it not to be spread out over another two years.