[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [RFC] DOCT: Declarative Org Capture Templates

From: No Wayman
Subject: Re: [RFC] DOCT: Declarative Org Capture Templates
Date: Fri, 24 Apr 2020 14:01:01 -0400
User-agent: mu4e 1.3.10; emacs 28.0.50

Nicolas Goaziou <address@hidden> writes:


No Wayman <address@hidden> writes:

* [RFC] DOCT: Declarative Org Capture Templates

Thank you for your work.

Thank you for taking the time to respond.

Disclaimer: I am only using very basic capture templates. So, I cannot comment realistically on the new syntax you suggest. In particular, the example you give is way too complex for me to understand the benefits of your syntax. I suggest to start out with showing simple use-cases.

Apologies, it's hard to strike a balance between showing something practical and over-writing.

- Is it compatible with the current syntax? If it isn't, is there a way
  to ease transition to the new syntax?

My package translates DOCT's syntax into the current syntax.
I have written a separate package that does basic translation from the current syntax to DOCT's as well.
It is not optimal yet, but does work for simple cases.
There are a few features of DOCT (property inheritance, management of hooks/contexts) that make it more difficult than just a syntax swap. I could come up with something more fully featured, but in my experience thus far, it does not take long to translate from one syntax to the other manually.

- Is it simple to use on simple use-cases?

I would say so. There is a single function that does the translation. For example:

(doct '("Example" :keys "e" :file ""))


(("e" "Example" entry (file "") nil :doct (:doct-name "Example" :keys "e" :file "")))

Part of my frustration of writing templates was always having to look up the structure of the template list. Keys, description, type, target (with its variations) and template-string (with its variations) is a lot to remember.

Whereas, with:

(doct '("Example" :keys "e" :file ""))

I need only remember that the description comes first. The keywords are more self-describing as well. There's an inherent complexity to the flexibility that org-capture offers, but this makes templates easier to write/read.

- Is it more capable than the current syntax, i.e., does it handle situations that are not possible, even in a convoluted way, currently?

- DOCT validates templates before runtime execution.

For exmaple, you have a template with an entry type of `'entry'
and you forget the leading star in the template string.
Days later you go to use that template. It's borked.

This is different from introducing a new syntax for capture templates.

Actually, `org-insert-place-item' and `org-capture-place-table-line'
both try to fix misshaped templates already. OTOH
`org-capture-place-entry' merely calls `org-capture-verify-tree' on the
template, i.e., it barfs if the template is ill-defined. It is
a discrepancy we could fix independently on your new syntax.

I invite you to propose a patch for `org-capture-place-entry' so it does a better job at fixing the initial template, if needed. I'll gladly
apply it.

`org-capture-place-entry' is run after `org-capture' is invoked, so while I agree a patch could improve the error, the user still hits that error when they are using their capture template (defeating the point of org-capture letting you take a quick note without losing your current context). DOCT checks while converting declarations to templates, so the error is thrown before org-capture is used (almost like linting for templates).

Aside from that, most of what DOCT does is sugar for common use patterns I've observed in others' org-capture-templates.
For example, adding per-declaration hooks:

Without DOCT:

;;rest of template configured elsewhere...
;;make sure you update this if you ever change the key for this template!
(defun my-org-template-hook ()
 (when (string= (org-capture-get :key t) "t")
   (message "Template \"t\" selected.")))

(add-hook 'org-capture-mode-hook 'my-org-template-hook)

With DOCT:

(doct `("Example" :keys "t" :file ""
:hook (lambda () (message "Template %s selected." (doct-get :keys)))))

DOCT ensures that function is only run for that template without having the user manually filter against `org-capture-plist's :key. It also allows the user to do this inline with the rest of the declaration vs spreading it out.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]