Colons in :var header arguments

Colons in :var header arguments

[Stefano Ghirlanda]

Hi everyone,

I have been using org-mode for reproducible research for many years
now. This is my first message: thanks to everyone who is involved in
org-mode development and maintenance!

I have run into an inconvenience in that colons in :var header
arguments to source blocks are invariably interpreted as referring to
another file. However, I use cleveref in LaTeX export (via org-ref) to
automatically format references using labels like tab:data, and in
these cases :var data=tab:data gives a reference not found because tab
is interpreted as a filename.

I have found a workaround in that I can use #+name: data to name the
table as well as \label{tab:data} in the table's #+caption: line, and
this works. But I was wondering if it would be cleaner to change this
behavior to interpreting tab:data as referring to a file only if
#+name: tab:data is not found in the current file. I think this would
break very few org files currently in the world, because presumably
people using the external file mechanism have not been using the
cleveref mechanism, otherwise this would have popped up already :) In
org files that use external references only, the change would be
invisible. I see the magic happens in org-ref-resolve in org-ref.el,
but I don't feel confident enough to mess with that myself.

Thanks again for one of the most useful pieces of software around.

-- 
Stefano Ghirlanda
CTO, DataWorks - https://dataworks.consulting
Guest Professor - Stockholm University Centre for Cultural Evolution

Re: Colons in :var header arguments

[Ihor Radchenko]

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

Stefano Ghirlanda <dr.ghirlanda@gmail.com> writes:

> I have run into an inconvenience in that colons in :var header
> arguments to source blocks are invariably interpreted as referring to
> another file. However, I use cleveref in LaTeX export (via org-ref) to
> automatically format references using labels like tab:data, and in
> these cases :var data=tab:data gives a reference not found because tab
> is interpreted as a filename.

I agree that it is a problem.
Attaching tentative patch that will make Org babel fall back to
searching in current file when FILE in FILE:REF does not exist.

It is technically a breaking change. If this is affecting someone's
workflow, please chime in.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-babel-ref-resolve-Search-current-buffer-when-FIL.patch --]
[-- Type: text/x-patch, Size: 2682 bytes --]

From 024cc1e6b31e9e3e9e4b8d3aee83221cb3326ee2 Mon Sep 17 00:00:00 2001
Message-ID: <024cc1e6b31e9e3e9e4b8d3aee83221cb3326ee2.1697883034.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sat, 21 Oct 2023 13:08:55 +0300
Subject: [PATCH] org-babel-ref-resolve: Search current buffer when FILE in
 FILE:REF does not exist

* lisp/ob-ref.el (org-babel-ref-resolve): Only search in other file
when FILE in FILE:REF exists.
* doc/org-manual.org (Passing arguments):
* etc/ORG-NEWS (Babel references =FILE:REFERENCE= now search current
buffer when =FILE= does not exist): Document the change.

Reported-by: Stefano Ghirlanda <dr.ghirlanda@gmail.com>
Link: https://orgmode.org/list/CAK_gY-Q4f82dbDQgyS+FfyeQaHAMXHqygq3e6ZsWnEj-+eoG9A@mail.gmail.com
---
 doc/org-manual.org | 4 ++++
 etc/ORG-NEWS       | 6 ++++++
 lisp/ob-ref.el     | 5 +++--
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index c0e9c8d7e..9a51a38a1 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17764,6 +17764,10 @@ *** Passing arguments
 
 : :var NAME=FILE:REFERENCE
 
+When =FILE= does not exist, the reference is searched in the current
+file, using the verbatim reference.  This way,
+=:var table=tbl:example= will be searched inside the current buffer.
+
 Here are examples of passing values by reference:
 
 - table ::
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 985488016..f64081964 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,6 +13,12 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
 
 * Version 9.7 (not released yet)
 ** Important announcements and breaking changes
+*** Babel references =FILE:REFERENCE= now search current buffer when =FILE= does not exist
+
+When =FILE= does not exist, the reference is searched in the current
+file, using the verbatim reference.  This way,
+=:var table=tbl:example= will be searched inside the current buffer.
+
 *** New export option ~org-export-expand-links~
 
 The new option makes Org expand environment variables in link and INCLUDE paths.
diff --git a/lisp/ob-ref.el b/lisp/ob-ref.el
index fd6927ccf..b7858569a 100644
--- a/lisp/ob-ref.el
+++ b/lisp/ob-ref.el
@@ -156,8 +156,9 @@ (defun org-babel-ref-resolve (ref)
 	  (when (string-match "^\\(.+\\):\\(.+\\)$" ref)
 	    (setq split-file (match-string 1 ref))
 	    (setq split-ref (match-string 2 ref))
-	    (find-file split-file)
-	    (setq ref split-ref))
+            (when (file-exists-p split-file)
+	      (find-file split-file)
+	      (setq ref split-ref)))
 	  (org-with-wide-buffer
 	   (goto-char (point-min))
 	   (let* ((params (append args '((:results . "none"))))
-- 
2.42.0


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>

Re: Colons in :var header arguments

[Stefano Ghirlanda]

Thanks, and sorry for the slow reply! I was wondering if it would be
more intuitive to try to resolve the reference in the same file before
looking in other files. I think this would make little practical
difference as I think files named sec, tab, eq and fig are rare
(although I often use fig for a figure directory, I wonder what
happens then). But looking externally first is more compatible with
current behavior, so maybe that should have priority.

Thanks again for considering.

On Sat, Oct 21, 2023 at 3:11 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Stefano Ghirlanda <dr.ghirlanda@gmail.com> writes:
>
> > I have run into an inconvenience in that colons in :var header
> > arguments to source blocks are invariably interpreted as referring to
> > another file. However, I use cleveref in LaTeX export (via org-ref) to
> > automatically format references using labels like tab:data, and in
> > these cases :var data=tab:data gives a reference not found because tab
> > is interpreted as a filename.
>
> I agree that it is a problem.
> Attaching tentative patch that will make Org babel fall back to
> searching in current file when FILE in FILE:REF does not exist.
>
> It is technically a breaking change. If this is affecting someone's
> workflow, please chime in.
>
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> 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>



-- 
Stefano Ghirlanda
CTO, DataWorks - https://dataworks.consulting
Guest Professor - Stockholm University Centre for Cultural Evolution

Re: Colons in :var header arguments

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> Stefano Ghirlanda <dr.ghirlanda@gmail.com> writes:
>
>> I have run into an inconvenience in that colons in :var header
>> arguments to source blocks are invariably interpreted as referring to
>> another file. However, I use cleveref in LaTeX export (via org-ref) to
>> automatically format references using labels like tab:data, and in
>> these cases :var data=tab:data gives a reference not found because tab
>> is interpreted as a filename.
>
> I agree that it is a problem.
> Attaching tentative patch that will make Org babel fall back to
> searching in current file when FILE in FILE:REF does not exist.
>
> It is technically a breaking change. If this is affecting someone's
> workflow, please chime in.

No objections have been raised after one month.
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b5cfc311d

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>