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

[No Wayman <iarchivedmywholelife@gmail.com>]

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


> - :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.
> + :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
> #<buffer CAPTURE-test.org> 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?