Bad interaction between org-capture entry type and file+function target?

Bad interaction between org-capture entry type and file+function target?

[Visuwesh]

[-- Attachment #1: Type: text/plain, Size: 2495 bytes --]

In the attached file "test.org", I want to capture new headings above
"Projects" always.  To achieve this, I used a file+function target to
move the point above "Projects" like below

    (let* ((heading "test")
           (file "tttt.pdf")
           (org-capture-templates
        `(("n" "blah"
               entry
               (file+function "/tmp/test.org"
                              ,(lambda ()
                     (goto-char (point-min))
                     (re-search-forward "^\\* Projects")
                     (goto-char (match-beginning 0))
                     (insert "\n")
                     (forward-char -1)))
           ,(concat "* " heading "\n"
                ":PROPERTIES:\n"
                ":NOTER_DOCUMENT: " file "\n"
                ":END:\n\n")
           :immediate-finish t
           :empty-lines-before 1))))
      (org-capture nil "n"))

However, when evaluating this sexp, the heading "test" is always
appended to the end of file contrary to what the docstring says:

    (file+function "path/to/file" function-finding-location)
        A function to find the right location in the file

This is because of the 'else' clause in the cond form in
org-capture-place-entry:

    (when exact-position (goto-char exact-position))
    (cond
     ;; Force insertion at point.
     (insert-here?
      ....)
     ;; Insert as a child of the current entry.
     ((org-capture-get :target-entry-p)
      ...)
     ;; Insert as a top-level entry at the beginning of the file.
     (reversed?
      ...)
     ;; Otherwise, insert as a top-level entry at the end of the file.
     (t (goto-char (point-max))
        ^^^^^^^^^^^^^^^^^^^^^^^
        ;; Make sure that last point is not folded.
        (org-fold-core-cycle-over-indirect-buffers
          (org-fold-region (max 1 (1- (point-max))) (point-max) nil))))

Should this be here?  Am I misunderstanding the documentation?  After
all, it is too terse (the same text is in the Info manual too).  The
documentation for the 'entry' type does not mention this quirk either:

    entry       an Org node, with a headline.  Will be filed
                as the child of the target entry or as a  
                top-level entry.  Its default template is:
                  "* %?\n%a"

The documentation for :prepend does mention that entries will be
inserted at the end if it is nil but I would think that using a function
would rule this out.

Changing the type to 'plain' from 'entry' works as expected though.


[-- Attachment #2: test.org --]
[-- Type: text/plain, Size: 151 bytes --]

* Heading 1
blah blah blah

* Heading 2
AAAAAAAA

* Projects
** Some subheading
something else here

* Glossary
** Some more subheading
something here

Re: Bad interaction between org-capture entry type and file+function target?

[Visuwesh]

[வியாழன் நவம்பர் 21, 2024] Visuwesh wrote:

> In the attached file "test.org", I want to capture new headings above
> "Projects" always.  To achieve this, I used a file+function target to
> move the point above "Projects" like below
>
> [...]
>
> However, when evaluating this sexp, the heading "test" is always
> appended to the end of file contrary to what the docstring says:
>
>     (file+function "path/to/file" function-finding-location)
>         A function to find the right location in the file
>
> This is because of the 'else' clause in the cond form in
> org-capture-place-entry:
>
> [...]
>
> Should this be here?  Am I misunderstanding the documentation?  After
> all, it is too terse (the same text is in the Info manual too).  The
> documentation for the 'entry' type does not mention this quirk either:
>
>     entry       an Org node, with a headline.  Will be filed
>                 as the child of the target entry or as a  
>                 top-level entry.  Its default template is:
>                   "* %?\n%a"
>
> The documentation for :prepend does mention that entries will be
> inserted at the end if it is nil but I would think that using a function
> would rule this out.
>
> Changing the type to 'plain' from 'entry' works as expected though.

I just thought of a situation where this behaviour would be desired: a
template could use FUNCTION-FINDING-LOCATION to ask the user to choose a
heading (from a list, using org-ql, etc.) to capture the entry to go
_under_ it.  Here, the function would simply move the point to be on the
heading.
[ I am actually in the process of writing such a capture template.  ]

So perhaps an indicator to tell org-capture that I want to insert the
heading exactly _at_point_ is required instead?

Re: Bad interaction between org-capture entry type and file+function target?

[Ihor Radchenko]

Visuwesh <visuweshm@gmail.com> writes:

> I just thought of a situation where this behaviour would be desired: a
> template could use FUNCTION-FINDING-LOCATION to ask the user to choose a
> heading (from a list, using org-ql, etc.) to capture the entry to go
> _under_ it.  Here, the function would simply move the point to be on the
> heading.
> [ I am actually in the process of writing such a capture template.  ]
>
> So perhaps an indicator to tell org-capture that I want to insert the
> heading exactly _at_point_ is required instead?

That's what :insert-here is for.

By default, capture location is an entry/list/table line where we want
to put capture template. Usually, it means _under_ entry, at the
begin/end of a list, begin/end of a table, etc.

Clearly, it is not documented well enough. We should improve the docs.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>