Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture

[Ihor Radchenko]

Valentin Herrmann  writes:

> * lisp/org-capture.el:
> (org-capture-templates): Document the new template options.
> (org-capture-before-view-hook): Add new hook for parity with the
> template options.
> (org-capture): Implement the new template options.
> (org-capture-finalize): Implement the new template options.
> (org-capture-kill): Remove unneeded line.
> * doc/org-manual.org (Template elements): Document the new template options
>
> This change comes from my personal config, where I use e.g. the option
> `:before-finalize-hook' to capture an task automatically, whenever I
> capture using a certain template.

An equivalent patch has been applied in
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=7f3a6cf6e72fe9968c6ef32211c754b7fe0172b6

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture

[Ihor Radchenko]

Valentin Herrmann  writes:

> * lisp/org-capture.el:
> (org-capture-templates): Document the new template options.
> (org-capture-before-view-hook): Add new hook for parity with the
> template options.
> (org-capture): Implement the new template options.
> (org-capture-finalize): Implement the new template options.
> (org-capture-kill): Remove unneeded line.
> * doc/org-manual.org (Template elements): Document the new template options

An equivalent patch has been applied in
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=7f3a6cf6e72fe9968c6ef32211c754b7fe0172b6

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture

[Ihor Radchenko]

Valentin Herrmann  writes:

> * lisp/org-capture.el:
> (org-capture-templates): Document the new template options.
> (org-capture-before-view-hook): Add new hook for parity with the
> template options.
> (org-capture): Implement the new template options.
> (org-capture-finalize): Implement the new template options.
> (org-capture-kill): Remove unneeded line.
> * doc/org-manual.org (Template elements): Document the new template options

> This change comes from my personal config, where I use e.g. the option
> `:before-finalize-hook' to capture an task automatically, whenever I
> capture using a certain template.

Thanks! This addition looks reasonable.

> +(if-let ((bvh (org-capture-get :before-view-hook)))
> +(funcall bvh))
> ...
> +  (when-let ((pfh (org-capture-get :prepare-finalize-hook)))
> +(funcall pfh))
> ...
> +(when-let ((bfh (org-capture-get :before-finalize-hook)))
> +  (funcall bfh
> ...
> +(when-let ((afh (org-capture-get :after-finalize-hook)))
> +  (funcall afh))

You should use run-hooks, not funcall. Hook must be a list of functions,
not a single function. By definition.

Also, do not use if-let/when-let. They are not loaded by default in
Emacs 26, which is still supported.

> -  (run-hooks 'org-capture-before-finalize-hook))
> +  (unless org-note-abort
> +(run-hooks 'org-capture-before-finalize-hook)
> ...
> -  (let ((org-note-abort t)
> - (org-capture-before-finalize-hook nil))
> +  (let ((org-note-abort t))
>  (org-capture-finalize)))

> (org-capture-finalize): Implement the new template options.
> (org-capture-kill): Remove unneeded line.

This change looks reasonable, but please document the rationale better
in the commit message. The current message is not clear.

Best,
Ihor

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture (Valentin Herrmann)

[Ihor Radchenko]

No Wayman  writes:

>> I think Nicolas gave some reasonable comments, didn't he? He 
>> suggested
>> to incorporate some of the ideas into the existing Org mode 
>> code.
>>
>> https://orgmode.org/list/87wo66t8i7@gmail.com
>
> I believe you're referring to:
>
> https://list.orgmode.org/87y2qlgq33@nicolasgoaziou.fr/
>
> He had some reasonable questions about the design, but said he 
> only uses very basic capture templates, and could not comment 
> beyond that on the design. The hope was that people who use more 
> of org-capture's features would chime in. That didn't happen.

I just pinged that thread again. Note that I strongly support adding
doct to Org.

> Of course doct's features could be added to org-capture in a 
> piecemeal fashion, but I'm not too keen on contributing anything 
> non-trivial to Org these days. Too much back and forth coupled 
> with discussion that can stall due to lack of interest. 
> e.g.

> https://list.orgmode.org/87h7e6dluc@gmail.com/
> https://list.orgmode.org/87tuit73ij@gmail.com/

I cannot comment on the lexical binding thing. I do not really know
lexical binding internals enough to judge what kind of problem that
patch is trying to solve. However, Bastien commented on the second
patch. I do find it useful as well. I think the only problem with that
patch is that it is not listed in updates.orgmode.org and Bastien missed
your last reply.

Best,
Ihor

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture (Valentin Herrmann)

[Greg Minshall]

fwiw...

> I've implemented what you're proposing here (and much more) in a 
> package you may find useful a couple years ago. I pitched adopting 
> some of the ideas into org-mode proper and was willing to do the 
> work. My proposal was met with enthusiastic silence:
> 
> https://www.github.com/progfolio/doct

i've been using doct for a while, and have been very happy with it.

(thanks for implementing it.)

cheers, Greg

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture (Valentin Herrmann)

[No Wayman]

Ihor Radchenko  writes:


No Wayman  writes:

I've implemented what you're proposing here (and much more) in 
a 
package you may find useful a couple years ago. I pitched 
adopting 
some of the ideas into org-mode proper and was willing to do 
the 
work. My proposal was met with enthusiastic silence:


https://www.github.com/progfolio/doct


I think Nicolas gave some reasonable comments, didn't he? He 
suggested
to incorporate some of the ideas into the existing Org mode 
code.


https://orgmode.org/list/87wo66t8i7@gmail.com

Best,
Ihor


I believe you're referring to:

https://list.orgmode.org/87y2qlgq33@nicolasgoaziou.fr/

He had some reasonable questions about the design, but said he 
only uses very basic capture templates, and could not comment 
beyond that on the design. The hope was that people who use more 
of org-capture's features would chime in. That didn't happen.


Of course doct's features could be added to org-capture in a 
piecemeal fashion, but I'm not too keen on contributing anything 
non-trivial to Org these days. Too much back and forth coupled 
with discussion that can stall due to lack of interest. 
e.g.


https://list.orgmode.org/87h7e6dluc@gmail.com/
https://list.orgmode.org/87tuit73ij@gmail.com/

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture (Valentin Herrmann)

[Ihor Radchenko]

No Wayman  writes:

> I've implemented what you're proposing here (and much more) in a 
> package you may find useful a couple years ago. I pitched adopting 
> some of the ideas into org-mode proper and was willing to do the 
> work. My proposal was met with enthusiastic silence:
>
> https://www.github.com/progfolio/doct

I think Nicolas gave some reasonable comments, didn't he? He suggested
to incorporate some of the ideas into the existing Org mode code.

https://orgmode.org/list/87wo66t8i7@gmail.com

Best,
Ihor

Re: [PATCH] lisp/org-capture.el: Add hook & hook options to org-capture (Valentin Herrmann)

[No Wayman]

I've implemented what you're proposing here (and much more) in a 
package you may find useful a couple years ago. I pitched adopting 
some of the ideas into org-mode proper and was willing to do the 
work. My proposal was met with enthusiastic silence:


https://www.github.com/progfolio/doct


- :prependNormally newly captured information will 
be appended at
- the target location (last child, last 
table line,
- last list item...).  Setting this property 
will

- change that.
+ :prepend   Normally newly captured information 
will be appended at
+the target location (last child, last 
table line,
+last list item...).  Setting this 
property will

+change that.


Are the white space changes to unrelated properties necessary?
  

+(defcustom org-capture-before-view-hook nil
+  "Hook that is run right after the capture buffer is made 
current.

+The buffer is still narrowed."
+  :group 'org-capture
+  :version "28.1"
+  :type 'hook)
+


This functionality is already provided by `org-capture-mode-hook'. 
Instead of introducing another hook, that can be utilized. An 
illustration using doct's :hook keyword which runs functions 
during org-capture-mode-hook:


Yodel[1] Report 2022-02-08 14:16:58
===

--8<---cut here---start->8---
(yodel
 :save "org-capture-mode-hook-example"
 :packages*
 doct
 :post*
 (require 'org-capture)
 (require 'doct)
 (let ((org-capture-templates
   (doct
`("test"
  :keys "t"
  :file "/tmp/test.org"
  :template "* test"
  :immediate-finish t
  :hook (lambda nil
(message "%S narrowed?: %S"
 (current-buffer)
 (buffer-narrowed-p)))
   (org-capture nil "t")))
--8<---cut here---end--->8---

STDOUT
==

Loading 
/tmp/org-capture-mode-hook-example/straight-bootstrap-snippet.el 
(source)...

Clipboard pasted as level 1 subtree
# narrowed?: t


Environment
===

- emacs version: GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, 
 GTK+ Version 3.24.31, cairo version 1.17.4)

of 2022-01-13
- system type: gnu/linux

Packages


- doct 
 https://github.com/progfolio/doct/commit/9ed9b8c7f7e2ea2d2fb739d65ae4626a1cf16b9f


[1] https://www.github.com/progfolio/yodel


+
+(run-hooks 'org-capture-before-view-hook)
+(if-let ((bvh (org-capture-get :before-view-hook)))
+(funcall bvh))


This pattern implies that functions added via template keywords 
will be run after the equivalent global hooks. That should be 
documented. This pattern could be improved by let-binding each 
hook and adding the templates functions. e.g.



(let ((org-capture-mode-hook
  (append org-capture-mode-hook (org-capture-get :hook t
 (run-hooks 'org-capture-mode-hook))


Note the use of the non-nil LOCAL argument in org-capture-get.
You want to ensure you're accessing the correct plist in the case 
of overlapping capture processes.


   ;; FIXME: This does not do the right thing, we need to remove 
   the

   ;; new stuff by hand it is easy: undo, then kill the buffer
-  (let ((org-note-abort t)
-   (org-capture-before-finalize-hook nil))
+  (let ((org-note-abort t))
 (org-capture-finalize)))
 
 (defun org-capture-goto-last-stored ()


Why was org-capture-before-finalize-hook bound to nil here and 
what is the reason for changing that?

[PATCH] lisp/org-capture.el: Add hook & hook options to org-capture

[Valentin Herrmann]

* lisp/org-capture.el:
(org-capture-templates): Document the new template options.
(org-capture-before-view-hook): Add new hook for parity with the
template options.
(org-capture): Implement the new template options.
(org-capture-finalize): Implement the new template options.
(org-capture-kill): Remove unneeded line.
* doc/org-manual.org (Template elements): Document the new template options

This change comes from my personal config, where I use e.g. the option
`:before-finalize-hook' to capture an task automatically, whenever I
capture using a certain template.
---
 doc/org-manual.org  |  21 
 etc/ORG-NEWS|  26 ++
 lisp/org-capture.el | 123 +++-
 3 files changed, 124 insertions(+), 46 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2c54fde87..5efc2d797 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7817,6 +7817,27 @@ Now lets look at the elements of a template definition.  
Each entry in
   - ~:refile-targets :: Temporarily set ~org-refile-targets~ to the
 value of this property.
 
+  - ~:before-view-hook~ ::
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+  - ~:prepare-finalize-hook~ ::
+
+Hook that is run before the finalization starts.
+The capture buffer is current and still narrowed.
+
+  - ~:before-finalize-hook~ ::
+
+Hook that is run right before a capture process is finalized.
+The capture buffer is still current when this hook runs and it is
+widened to the entire buffer.
+
+  - ~:after-finalize-hook~ ::
+
+Hook that is run right after a capture process is finalized.
+Suitable for window cleanup.
+
  Template expansion
 :PROPERTIES:
 :DESCRIPTION: Filling in information about time and context.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 5a94e737e..25441027f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -63,6 +63,32 @@ list of various table options (between brackets in LaTeX 
export),
 since certain tabular environments, such as longtblr of the
 tabularray LaTeX package, provides this structure.
 
+*** New hook =org-capture-before-view-hook= for =org-capture= before view
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:before-view-hook= for =org-capture=
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:prepare-finalize-hook= for =org-capture=
+
+Hook that is run before the finalization starts.
+The capture buffer is current and still narrowed.
+
+*** New option =:before-finalize-hook= for =org-capture=
+
+Hook that is run right before a capture process is finalized.
+The capture buffer is still current when this hook runs and it is
+widened to the entire buffer.
+
+*** New option =:after-finalize-hook= for =org-capture=
+
+Hook that is run right after a capture process is finalized.
+Suitable for window cleanup.
+
 ** New functions and changes in function arguments
 
 *** New function ~org-element-cache-map~ for quick mapping across Org elements
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 5195b785e..27dd72ef8 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -235,64 +235,77 @@ template The template for creating the capture item.
 The rest of the entry is a property list of additional options.  Recognized
 properties are:
 
- :prependNormally newly captured information will be appended at
- the target location (last child, last table line,
- last list item...).  Setting this property will
- change that.
+ :prepend   Normally newly captured information will be appended at
+the target location (last child, last table line,
+last list item...).  Setting this property will
+change that.
 
- :immediate-finish   When set, do not offer to edit the information, just
- file it away immediately.  This makes sense if the
- template only needs information that can be added
- automatically.
+ :immediate-finish  When set, do not offer to edit the information, just
+file it away immediately.  This makes sense if the
+template only needs information that can be added
+automatically.
 
- :jump-to-captured   When set, jump to the captured entry when finished.
+ :jump-to-captured  When set, jump to the captured entry when finished.
 
- :refile-targets When exiting capture mode via `org-capture-refile', the
- variable `org-refile-targets' will be temporarily bound
- to the value of this property.
+ :refile-targetsWhen exiting capture mode via `org-capture-refile', the
+variable `

[PATCH] lisp/org-capture.el: Add hook & hook options to org-capture

[Valentin Herrmann]

* lisp/org-capture.el:
(org-capture-templates): Document the new template options.
(org-capture-before-view-hook): Add new hook for parity with the
template options.
(org-capture): Implement the new template options.
(org-capture-finalize): Implement the new template options.
(org-capture-kill): Remove unneeded line.
* doc/org-manual.org (Template elements): Document the new template options

This change comes from my personal config, where I use e.g. the option
`:before-finalize-hook' to capture an task automatically, whenever I
capture using a certain template.
---
 doc/org-manual.org  |  21 
 etc/ORG-NEWS|  26 ++
 lisp/org-capture.el | 123 +++-
 3 files changed, 124 insertions(+), 46 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2c54fde87..5efc2d797 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7817,6 +7817,27 @@ Now lets look at the elements of a template definition.  
Each entry in
   - ~:refile-targets :: Temporarily set ~org-refile-targets~ to the
 value of this property.
 
+  - ~:before-view-hook~ ::
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+  - ~:prepare-finalize-hook~ ::
+
+Hook that is run before the finalization starts.
+The capture buffer is current and still narrowed.
+
+  - ~:before-finalize-hook~ ::
+
+Hook that is run right before a capture process is finalized.
+The capture buffer is still current when this hook runs and it is
+widened to the entire buffer.
+
+  - ~:after-finalize-hook~ ::
+
+Hook that is run right after a capture process is finalized.
+Suitable for window cleanup.
+
  Template expansion
 :PROPERTIES:
 :DESCRIPTION: Filling in information about time and context.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 5a94e737e..25441027f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -63,6 +63,32 @@ list of various table options (between brackets in LaTeX 
export),
 since certain tabular environments, such as longtblr of the
 tabularray LaTeX package, provides this structure.
 
+*** New hook =org-capture-before-view-hook= for =org-capture= before view
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:before-view-hook= for =org-capture=
+
+Hook that is run right after the capture buffer is made current.
+The buffer is still narrowed.
+
+*** New option =:prepare-finalize-hook= for =org-capture=
+
+Hook that is run before the finalization starts.
+The capture buffer is current and still narrowed.
+
+*** New option =:before-finalize-hook= for =org-capture=
+
+Hook that is run right before a capture process is finalized.
+The capture buffer is still current when this hook runs and it is
+widened to the entire buffer.
+
+*** New option =:after-finalize-hook= for =org-capture=
+
+Hook that is run right after a capture process is finalized.
+Suitable for window cleanup.
+
 ** New functions and changes in function arguments
 
 *** New function ~org-element-cache-map~ for quick mapping across Org elements
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 5195b785e..27dd72ef8 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -235,64 +235,77 @@ template The template for creating the capture item.
 The rest of the entry is a property list of additional options.  Recognized
 properties are:
 
- :prependNormally newly captured information will be appended at
- the target location (last child, last table line,
- last list item...).  Setting this property will
- change that.
+ :prepend   Normally newly captured information will be appended at
+the target location (last child, last table line,
+last list item...).  Setting this property will
+change that.
 
- :immediate-finish   When set, do not offer to edit the information, just
- file it away immediately.  This makes sense if the
- template only needs information that can be added
- automatically.
+ :immediate-finish  When set, do not offer to edit the information, just
+file it away immediately.  This makes sense if the
+template only needs information that can be added
+automatically.
 
- :jump-to-captured   When set, jump to the captured entry when finished.
+ :jump-to-captured  When set, jump to the captured entry when finished.
 
- :refile-targets When exiting capture mode via `org-capture-refile', the
- variable `org-refile-targets' will be temporarily bound
- to the value of this property.
+ :refile-targetsWhen exiting capture mode via `org-capture-refile', the
+variable `