branch: externals/org
commit 507e0f4fa0f3c5ed3ed8c28d37ff9d8c91670e2b
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
org-capture-place-plain-text: Fix when target is on headline
* lisp/org-capture.el (org-capture-place-plain-text): When on
headline, insert into headline body, just as all other capture entry
types do.
(org-capture-templates): Clarify in the docstring what happens when
target points inside heading body.
* etc/ORG-NEWS (~org-capture~ target pointing to headline is now
handled uniformly for =plain= entry type): Announce the change.
Reported-by: Tianshu Wang <w...@tianshu.me>
Link: https://orgmode.org/list/m2tt46evux....@tianshu.me
---
etc/ORG-NEWS | 11 +++++++++++
lisp/org-capture.el | 41 +++++++++++++++++++++++++++++++++++------
2 files changed, 46 insertions(+), 6 deletions(-)
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 4cb7561a8b..b415cd2d9a 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -506,6 +506,17 @@ capture ~:tree-type~ options]], the internal variable
undocumented helper function ~org-datetree-insert-line~.
** Miscellaneous
+*** ~org-capture~ target pointing to headline is now handled uniformly for
=plain= entry type
+
+Previously, when using ~file+regexp~, ~file+function~ or ~function~, =plain=
entries
+were inserted right at the point according to regexp/function, even when point
is
+on an existing headline.
+
+Now, when target points to an existing headline, =plain= entries are
+inserted inside its body, honoring ~:prepend~ property. This is more
+consistent with how ~item~, ~checkitem~, and ~table-line~ templates
+are handled.
+
*** HTML export wraps ~<code>~ around all the exported src blocks
HTML export always uses ~<pre>~ tag around exported src blocks.
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 02a1ea8330..b18418bd5d 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -183,9 +183,10 @@ type The type of entry. Valid types are:
plain text to be inserted as it is.
target Specification of where the captured item should be placed.
- In Org files, targets usually define a node. Entries will
- become children of this node, other types will be added to the
- table or list in the body of this node.
+ In Org files, targets usually define a node. Entries
+ (type `entry') will become children of this node, other
+ types will be added to the table or list in the body of
+ this node.
<file-spec>
Most target specifications contain a file name. If that file
@@ -213,7 +214,7 @@ target Specification of where the captured item
should be placed.
For non-unique headings, the full outline path is safer
(file+regexp <file-spec> \"regexp to find location\")
- File to the entry matching regexp
+ File to the entry containing matching regexp
(file+olp+datetree <file-spec> \"Level 1 heading\" ...)
(file+olp+datetree <file-spec> function-returning-list-of-strings)
@@ -231,12 +232,38 @@ target Specification of where the captured item
should be placed.
File to the entry that is currently being clocked
(here)
- The position of point
+ The exact position to insert the template
(function function-finding-location)
Most general way: write your own function which both visits
the file and moves point to the right location
+
+ For (here) target, the template will be always inserted
+ in place.
+
+ When the target points to headline, the template will
+ be inserted into the headline body (for non-`entry' types)
+ or as an immediate child.
+
+ When the target points to text inside heading body, the
+ exact place where the template will be inserted depends
+ on its type:
+
+ entry will be inserted as a child of the Org
+ heading the point is in.
+
+ item, will be inserted in the nearest existing Org
+ checkitem list, if there is one. The list will be
+ searched from the point to the end of current
+ heading body.
+
+ table-line will be inserted into the nearest table, if any
+ searching from point to the end of current
+ heading body.
+
+ plain plain text will be inserted in place.
+
template The template for creating the capture item.
If it is an empty string or nil, a default template based on
the entry type will be used (see the \"type\" section above).
@@ -1525,7 +1552,7 @@ the text of the entry, before the first child. If not,
place the
template at the beginning or end of the file.
Of course, if exact position has been required, just put it there."
(cond
- ((org-capture-get :exact-position)
+ ((org-capture-get :insert-here)
(goto-char (org-capture-get :exact-position)))
((org-capture-get :target-entry-p)
;; Place the text into this entry.
@@ -1534,6 +1561,8 @@ Of course, if exact position has been required, just put
it there."
(org-end-of-meta-data t)
;; Go to end of the entry text, before the next headline.
(outline-next-heading)))
+ ((org-capture-get :exact-position)
+ (goto-char (org-capture-get :exact-position)))
(t
;; Beginning or end of file.
(goto-char (if (org-capture-get :prepend) (point-min) (point-max)))))
