emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [RFC] DOCT: Declarative Org Capture Templates
@ 2020-04-23 17:30 No Wayman
  2020-04-24 10:01 ` Nicolas Goaziou
  0 siblings, 1 reply; 16+ messages in thread
From: No Wayman @ 2020-04-23 17:30 UTC (permalink / raw)
  To: emacs-orgmode

[-- 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 --]

^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2022-03-29 14:53 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-04-23 17:30 [RFC] DOCT: Declarative Org Capture Templates No Wayman
2020-04-24 10:01 ` 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

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