emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: No Wayman <iarchivedmywholelife@gmail.com>
To: emacs-orgmode@gnu.org
Subject: [RFC] DOCT: Declarative Org Capture Templates
Date: Thu, 23 Apr 2020 13:30:25 -0400	[thread overview]
Message-ID: <87wo66t8i7.fsf@gmail.com> (raw)

[-- Attachment #1: Type: text/plain, Size: 4191 bytes --]

* [RFC] DOCT: Declarative Org Capture Templates

I've been working on an alternative syntax for 
The result is a package called "DOCT" (declarative org capture 


A brief list of what I believe to be improvements over the current 

- 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.
You have a number of options:
- forget about whatever you wanted to capture and press on with 
  your original task
- manually take a note about what you originally wanted to capture 
  and another note to fix the broken template
- drop what you're doing and fix everything
None of these are ideal and all of them result in distraction.
DOCT performs a number of checks ahead of time when possible to 
prevent these types of errors.

- DOCT makes the parent/child relationship between templates 

`org-capture-templates` is a flat list. The relationship between 
templates is hardcoded in each template's "keys" value.
If you want to change the key for a top-level menu, you must then 
change it in each descendant's keys. DOCT uses nested plists
and implements property inheritance.

- DOCT manages per-template hooks/contexts.

Currently if you want to have a hook run for a particular 
template, you have to filter against `org-capture-plist' to check 
for the appropriate :key value.
As stated above, this is fragile and you have to update that key 
value in numerous places if it ever changes. The same goes for 
DOCT allows specifying per-template contexts and hooks with the 
rest of the template's configuration.

- DOCT makes adding custom metadata to templates easy.

A common pattern for attaching data to a template is to add to 
`org-capture-plist'. This pollutes `org-capture-plist' more than 
DOCT adds custom data to `org-capture-plist' under a single :doct 
keyword and allows users to access that data in the template 
string with familiar %-escape syntax.

This example is one I use daily for taking notes in programming 

#+begin_src emacs-lisp
   :keys "n"
   :file ,(defun my/project-note-file ()
            (let ((file (expand-file-name "notes.org" (when 
            (functionp 'projectile-project-root)
              (with-current-buffer (find-file-noselect file)
                ;;set to utf-8 because we may be visiting raw file
                (setq buffer-file-coding-system 'utf-8-unix)
                (when-let ((headline (doct-get :headline)))
                  (unless (org-find-exact-headline-in-buffer 
                    (goto-char (point-max))
                    (insert "* " headline)
                    (org-set-tags (downcase headline))))
                (unless (file-exists-p file) (write-file file))
   :template (lambda () (concat  "* %{todo-state} " (when 
   (y-or-n-p "link?") "%A\n") "%?"))
   :todo-state "TODO"
   :children (("bug"           :keys "b" :headline "Bugs")
              ("documentation" :keys "d" :headline 
              ("enhancement"   :keys "e" :headline "Enhancements" 
              :todo-state "IDEA")
              ("feature"       :keys "f" :headline "Features" 
              :todo-state "IDEA")
              ("optimization"  :keys "o" :headline 
              ("miscellaneous" :keys "m" :headline 
              ("security"      :keys "s" :headline "Security"))))

Each template inherits its parent's file finding function,template 
string, and a default :todo-state.
The template string access the child's :todo-state keyword with 
the "%{KEYWORD}" syntax in the template string.

I would be happy to work on getting these features into Org if 
there is any interest.
Any feedback is welcome.

Thanks, nv.

[-- Attachment #2: Type: text/html, Size: 7074 bytes --]

             reply	other threads:[~2020-04-23 17:31 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-23 17:30 No Wayman [this message]
2020-04-24 10:01 ` [RFC] DOCT: Declarative Org Capture Templates Nicolas Goaziou
2020-04-24 18:01   ` No Wayman
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:

  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=87wo66t8i7.fsf@gmail.com \
    --to=iarchivedmywholelife@gmail.com \
    --cc=emacs-orgmode@gnu.org \


* 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


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).