Re: [PATCH] org-capture.el: Allow `(here)' as a template target

[Tim Visher <tim.visher@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 1784 bytes --]

On Wed, Jun 21, 2023 at 6:29 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> Tim Visher <tim.visher@gmail.com> writes:
>
> > I've now created patches for updating the manual and NEWS file. Let me
> know
> > how they look!
>
> Thanks! The patches look good, and the commit messages look excellent.
>

٩( ᐛ )و


> You could, however, squash the patches together


Absolutely! Will do once we've approved the whole change. I will use the
commit message of 0001 for the whole patch.


> Also, may you update the docstring of `org-capture-templates'


Good catch! This has been done in patch 0004 now. Look good?


> "10.1.3.1 Template elements" section of Org manual?
>

I'm confused about what you're referring to here. Isn't that what 0002 does?

```
$ cat 0002-squash-doc-org-manual.org-Add-documentation-for-here.patch
From 4b4bf944129635637c6fd57076f1c963b4c27bf6 Mon Sep 17 00:00:00 2001
From: Tim Visher <tim.visher@gmail.com>
Date: Tue, 20 Jun 2023 15:11:58 -0400
Subject: [PATCH 2/4] squash! doc/org-manual.org: Add documentation for
 `(here)` target

---
 doc/org-manual.org | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 21582fe8e..76131f110 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7946,6 +7946,10 @@ Now lets look at the elements of a template
definition.  Each entry in

     File to the entry that is currently being clocked.

+  - =(here)= ::
+
+    The position of =point=.
+
   - =(function function-finding-location)= ::

     Most general way: write your own function which both visits the
--
2.40.1
```

Again, happy to squash and provide a single complete patch once we're all
done the review. Thanks again, Ihor! :)

[-- Attachment #1.2: Type: text/html, Size: 3072 bytes --]

[-- Attachment #2: 0002-squash-doc-org-manual.org-Add-documentation-for-here.patch --]
[-- Type: application/octet-stream, Size: 777 bytes --]

From 4b4bf944129635637c6fd57076f1c963b4c27bf6 Mon Sep 17 00:00:00 2001
From: Tim Visher <tim.visher@gmail.com>
Date: Tue, 20 Jun 2023 15:11:58 -0400
Subject: [PATCH 2/4] squash! doc/org-manual.org: Add documentation for
 `(here)` target

---
 doc/org-manual.org | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 21582fe8e..76131f110 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -7946,6 +7946,10 @@ Now lets look at the elements of a template definition.  Each entry in
 
     File to the entry that is currently being clocked.
 
+  - =(here)= ::
+
+    The position of =point=.
+
   - =(function function-finding-location)= ::
 
     Most general way: write your own function which both visits the
-- 
2.40.1


[-- Attachment #3: 0003-squash-etc-ORG-NEWS-Add-entry-for-here-capture-templ.patch --]
[-- Type: application/octet-stream, Size: 918 bytes --]

From bcd78dcc5805e578ed7d4b47704f7c271d88d76f Mon Sep 17 00:00:00 2001
From: Tim Visher <tim.visher@gmail.com>
Date: Tue, 20 Jun 2023 15:12:47 -0400
Subject: [PATCH 3/4] squash! etc/ORG-NEWS: Add entry for `(here)` capture
 template target support

---
 etc/ORG-NEWS | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index a24caddfe..3201918eb 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -294,6 +294,11 @@ skipped (with a warning) if the ox-icalendar export encounters them:
 Also note that only vanilla repeaters are currently exported; the
 special repeaters ~++~ and ~.+~ are skipped.
 
+*** Capture templates now support ~(here)~ as a target
+
+A capture template can target ~(here)~ which is the equivalent of
+invoking a capture template with a zero prefix.
+
 ** Miscellaneous
 *** =org-crypt.el= now applies initial visibility settings to decrypted entries
 
-- 
2.40.1


[-- Attachment #4: 0004-squash-Update-docstring-of-org-capture-templates.patch --]
[-- Type: application/octet-stream, Size: 878 bytes --]

From 2aebb9e2d41fbad080d9b8a84c2a885af7233686 Mon Sep 17 00:00:00 2001
From: Tim Visher <tim.visher@gmail.com>
Date: Wed, 21 Jun 2023 09:05:38 -0400
Subject: [PATCH 4/4] squash! Update docstring of org-capture-templates

---
 lisp/org-capture.el | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index f14e95c5c..40a7f78f1 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -220,6 +220,9 @@ target       Specification of where the captured item should be placed.
              (clock)
                 File to the entry that is currently being clocked
 
+             (here)
+                The position of point
+
              (function function-finding-location)
                 Most general way: write your own function which both visits
                 the file and moves point to the right location
-- 
2.40.1


[-- Attachment #5: 0001-org-capture.el-Allow-here-as-a-template-target 2.patch --]
[-- Type: application/octet-stream, Size: 1658 bytes --]

From 184098a426495d80c12fc7fa90218681a5bb1f0f Mon Sep 17 00:00:00 2001
From: Tim Visher <tim.visher@gmail.com>
Date: Fri, 12 May 2023 11:32:21 -0400
Subject: [PATCH 1/4] org-capture.el: Allow `(here)' as a template target

* lisp/org-capture.el (org-capture-set-target-location): Allow `(here)' as a template
target in addition to `here'.

Templates had no user accessible way to target the current location
directly from a capture template. Attempting to directly utilize the
behavior accessible through a 0 prefix arg exposed the inconsistent
treatment of the `:target` property in
`org-capture`. `org-capture-set-target-location` understood that it
could be both a symbol and a list, while `org-capture` itself required
it to be a list through its use of `car`.

This change opts to make `org-capture-set-target-location` more
liberal in what it accepts rather than making `org-capture` agree that
targets can be lists. This is because the manual implies, especially
in the `(clock)' entry, that targets are expected to be lists even if
they are meant as specific points.

TINYCHANGE
---
 lisp/org-capture.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index d4311dd20..f14e95c5c 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -991,7 +991,8 @@ Store them in the capture property list."
   (let ((target-entry-p t))
     (save-excursion
       (pcase (or target (org-capture-get :target))
-	(`here
+	((or `here
+             `(here))
 	 (org-capture-put :exact-position (point) :insert-here t))
 	(`(file ,path)
 	 (set-buffer (org-capture-target-buffer path))
-- 
2.40.1