emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: No Wayman <iarchivedmywholelife@gmail.com>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org
Subject: Re: [RFC] DOCT: Declarative Org Capture Templates
Date: Fri, 24 Apr 2020 14:01:01 -0400	[thread overview]
Message-ID: <87d07wkbkz.fsf@gmail.com> (raw)
In-Reply-To: <87y2qlgq33.fsf@nicolasgoaziou.fr>


Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> No Wayman <iarchivedmywholelife@gmail.com> 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 ""))

Returns:

(("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	other threads:[~2020-04-24 18:01 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-23 17:30 No Wayman
2020-04-24 10:01 ` Nicolas Goaziou
2020-04-24 18:01   ` No Wayman [this message]
2022-03-20 10:19     ` [RFC] DOCT: Declarative Org Capture Templates (easier template syntax) Ihor Radchenko
2022-03-20 13:17       ` Nicolas Goaziou
2022-03-21  9:14         ` Ihor Radchenko
2022-03-23 16:31           ` Nicolas Goaziou
2022-03-23 21:28             ` Tim Cross
2022-03-24  0:39             ` No Wayman
2022-03-26  8:30               ` Ihor Radchenko
2022-03-27 14:46                 ` Ihor Radchenko
2022-03-29 14:19                 ` Matt Price
2022-03-20 15:56       ` Mark Barton
2022-03-21  8:51         ` Ihor Radchenko
2022-03-23 14:32       ` João Pedro de Amorim Paula
2022-03-24 18:43       ` physiculus

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87d07wkbkz.fsf@gmail.com \
    --to=iarchivedmywholelife@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=mail@nicolasgoaziou.fr \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).