[BUG] org-lint tells to move #+name to wrong place in results block

[BUG] org-lint tells to move #+name to wrong place in results block

[gerard.vermeulen]

For the listings below org-lint tells me to move "#+name: OUT"
downwards:

    Line Trust Warning
      17 high   #+name: in results of evaluation will be replaced by
      re-evaluating the src block.  Use #+name in the block instead.

This is not true, and after I move it below "#+RESULTS: IN"
re-evalution makes "#+name: OUT" disappear.

#+header: :wrap "src emacs-lisp"
#+name: IN
#+begin_src emacs-lisp
3
#+end_src

#+name: OUT
#+RESULTS: IN
#+begin_src emacs-lisp
3
#+end_src

Listing [[IN]] produces listing [[OUT]], clicking each link in Org
jumps to the linked block, TAB-bing on "#+name: OUT" folds the
block, but exporting says:  Unable to resolve the link "OUT".

Org mode version 9.7-pre (release_9.6.17-1081-g83696b)

FR: would it be possible to resolve such links?

Regards -- Gerard

Re: [BUG] org-lint tells to move #+name to wrong place in results block

[Ihor Radchenko]

gerard.vermeulen@posteo.net writes:

> For the listings below org-lint tells me to move "#+name: OUT"
> downwards:
>
>     Line Trust Warning
>       17 high   #+name: in results of evaluation will be replaced by
>       re-evaluating the src block.  Use #+name in the block instead.
>
> This is not true

Good point.
The real problem is indeed different - when the source block has
:exports code, results will be removed and any links to OUT will become
invalid:

> ..., but exporting says:  Unable to resolve the link "OUT".

> FR: would it be possible to resolve such links?

What is the purpose? Why not simply leaving the result name same as the
source block?

-- 
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: [BUG] org-lint tells to move #+name to wrong place in results block

[gerard.vermeulen]

On 22.01.2024 19:15, Ihor Radchenko wrote:
> gerard.vermeulen@posteo.net writes:
> 
>> For the listings below org-lint tells me to move "#+name: OUT"
>> downwards:
>> 
>>     Line Trust Warning
>>       17 high   #+name: in results of evaluation will be replaced by
>>       re-evaluating the src block.  Use #+name in the block instead.
>> 
>> This is not true
> 
> Good point.
> The real problem is indeed different - when the source block has
> :exports code, results will be removed and any links to OUT will become
> invalid:
> 
>> ..., but exporting says:  Unable to resolve the link "OUT".
> 
>> FR: would it be possible to resolve such links?
> 
> What is the purpose? Why not simply leaving the result name same as the
> source block?

I have Python "IN" blocks generating Python "OUT" blocks that may end up
on different pages after exporting to LaTeX and PDF.
The FR would allow to link always to the correct page.

I have 10 org-lint warnings of this type for a 150 page PDF document.
Most of those "OUT" blocks are on the same page as their corresponding
"IN" blocks, but I have worked around this limitation.

I can live without the requested feature, but it would be a way to 
eliminate
an org-lint test.

Best regards -- Gerard

Re: [BUG] org-lint tells to move #+name to wrong place in results block

[Ihor Radchenko]

gerard.vermeulen@posteo.net writes:

>>> FR: would it be possible to resolve such links?
>> 
>> What is the purpose? Why not simply leaving the result name same as the
>> source block?
>
> I have Python "IN" blocks generating Python "OUT" blocks that may end up
> on different pages after exporting to LaTeX and PDF.
> The FR would allow to link always to the correct page.

Patches welcome.
Another option is :post argument that will add the necessary #+name. 

> I have 10 org-lint warnings of this type for a 150 page PDF document.
> Most of those "OUT" blocks are on the same page as their corresponding
> "IN" blocks, but I have worked around this limitation.
>
> I can live without the requested feature, but it would be a way to 
> eliminate
> an org-lint test.

"i" in org-lint buffer will remove all the warnings similar to warning
at point.

-- 
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: [PATCH] Make an org-lint warning more helpful

[gerard.vermeulen]

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



On 22.01.2024 19:59, Ihor Radchenko wrote:
> gerard.vermeulen@posteo.net writes:
> 
>>>> FR: would it be possible to resolve such links?
>>> 
>>> What is the purpose? Why not simply leaving the result name same as 
>>> the
>>> source block?
>> 
>> I have Python "IN" blocks generating Python "OUT" blocks that may end 
>> up
>> on different pages after exporting to LaTeX and PDF.
>> The FR would allow to link always to the correct page.
> 
> Patches welcome.
> Another option is :post argument that will add the necessary #+name.
> 
I see that my FR is already an Org feature.

Attached patch makes the relevant org-lint warning more helpful for 
fixing
user's Org buffers.

I still have to think about your ":post argument" option to and #+name.

Regards -- Gerard


[-- Attachment #2: 0001-Make-an-org-lint-warning-more-helpful.patch --]
[-- Type: application/octet-stream, Size: 1444 bytes --]

From 373bf5bc185917961046de629ea78296e06d0931 Mon Sep 17 00:00:00 2001
From: Gerard Vermeulen <gerard.vermeulen@posteo.net>
Date: Tue, 23 Jan 2024 09:12:48 +0100
Subject: [PATCH] Make an org-lint warning more helpful

* lisp/org-lint.el (org-lint-named-result): Make the warning
correspond with section "16.7 Exporting Code Blocks" of the manual.

Link: https://list.orgmode.org/60f395fcacacdc6a7d9de3cd7a00032b@posteo.net/
---
 lisp/org-lint.el | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lisp/org-lint.el b/lisp/org-lint.el
index 893e504d3..8290b621f 100644
--- a/lisp/org-lint.el
+++ b/lisp/org-lint.el
@@ -1362,10 +1362,11 @@ Use \"export %s\" instead"
 (defun org-lint-named-result (ast)
   (org-element-map ast org-element-all-elements
     (lambda (el)
-      (when (and (org-element-property :results el)
-                 (org-element-property :name el))
+      (when-let ((results (org-element-property :results el))
+                 (name (org-element-property :name el)))
         (list (org-element-begin el)
-              "#+name: in results of evaluation will be replaced by re-evaluating the src block.  Use #+name in the block instead.")))))
+              (format "To resolve links to %S in evaluation results, add e.g. \":exports both\" to evaluated block."
+                      name))))))
 
 (defun org-lint-spurious-colons (ast)
   (org-element-map ast '(headline inlinetask)
-- 
2.42.0

Re: [BUG] org-lint tells to move #+name to wrong place in results block

[gerard.vermeulen]

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



On 22.01.2024 19:59, Ihor Radchenko wrote:
> gerard.vermeulen@posteo.net writes:
> 
>>>> FR: would it be possible to resolve such links?
>>> 
>>> What is the purpose? Why not simply leaving the result name same as 
>>> the
>>> source block?
>> 
>> I have Python "IN" blocks generating Python "OUT" blocks that may end 
>> up
>> on different pages after exporting to LaTeX and PDF.
>> The FR would allow to link always to the correct page.
> 
> Patches welcome.

This patch completes my "Make an org-lint warning more helpful" patch.

I have found that CAPTION keywords  in the "name-result-example" in the
manual are essential to produce correct links.

In case the relevant blocks have e.g. ":exports both", Org handles
this, but:
1. HTML export requires captions to produce links with unequivocal
    "link texts" which are numbers in the HTML output.
2. LaTeX export requires captions to produce captions with labels like
    =\caption{\label{path}desc}=.
Tested on example below:

Produced by listing [[IN]].

#+caption: Results block
#+name: OUT
#+RESULTS: IN
#+begin_src emacs-lisp :exports code
6
#+end_src

#+caption: Source block
#+header: :wrap "src emacs-lisp :exports code"
#+name: IN
#+begin_src emacs-lisp :exports both
6
#+end_src

Listing [[IN]] produces listing [[OUT]].

 From inspecting HTML or LaTeX output using this example
for the difference between with and without captions it is
easy to see that only with captions the output is correct.

The patch tries to add this information to the manual.

Regards -- Gerard

[-- Attachment #2: 0001-doc-org-manual-Add-CAPTION-keywords-to-named-results.patch --]
[-- Type: application/octet-stream, Size: 1803 bytes --]

From e883fd9b67c1b6e742fc27e86b66ce70d50f00b0 Mon Sep 17 00:00:00 2001
From: Gerard Vermeulen <gerard.vermeulen@posteo.net>
Date: Tue, 23 Jan 2024 14:32:38 +0100
Subject: [PATCH] doc/org-manual: Add CAPTION keywords to named results example

* doc/org-manual (Exporting Code Blocks): Add CAPTION keywords to
named results example.  Exporting links without CAPTION keywords may
silently fail (HTML) or during LaTeX compilation.
---
 doc/org-manual.org | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6c52858e6..ae9e85831 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18931,11 +18931,13 @@ Results of evaluation of a named block can also be explicitly named
 using a separate =NAME= keyword.  The name value set via =NAME=
 keyword will be preferred over the parent source block.
 
+: #+CAPTION: Source block
 : #+NAME: code name
 : #+BEGIN_SRC emacs-lisp :exports both value
 : (+ 1 2)
 : #+END_SRC
 :
+: #+CAPTION: Results block
 : #+NAME: results name
 : #+RESULTS: code name
 : 3
@@ -18944,9 +18946,10 @@ keyword will be preferred over the parent source block.
 : Another [[results name][link]] will point to the results.
 
 Explicit setting of the result name may be necessary when a named code
-block is exported using =:exports both=.  Links to such block may
+block is exported using =:exports both=.  Links to such blocks may
 arbitrarily point either to the code block or to its results when
-results do not have a distinct name.
+results do not have a distinct name.  The =CAPTION= keywords ensure
+that link descriptions are passed to the export output.
 
 Note that all the links pointing to a source block exported using
 =:exports none= will be broken.  This will make export process fail,
-- 
2.42.0

Re: [PATCH] Make an org-lint warning more helpful

[Ihor Radchenko]

gerard.vermeulen@posteo.net writes:

> Attached patch makes the relevant org-lint warning more helpful for 
> fixing
> user's Org buffers.

Thanks!
I applied an alternative patch.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=d2986be07
Handled.

-- 
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>

[BUG] ox-latex produces broken references to src code listings without caption (was: [BUG] org-lint tells to move #+name to wrong place in results block)

[Ihor Radchenko]

gerard.vermeulen@posteo.net writes:

> I have found that CAPTION keywords  in the "name-result-example" in the
> manual are essential to produce correct links.

It should not be essential. What you demonstrated is two bugs in Org mode.

> In case the relevant blocks have e.g. ":exports both", Org handles
> this, but:
> 1. HTML export requires captions to produce links with unequivocal
>     "link texts" which are numbers in the HTML output.

Fixed, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=ea529007d

> 2. LaTeX export requires captions to produce captions with labels like
>     =\caption{\label{path}desc}=.

`org-latex-link' assumes that it is safe to use
\ref{<org-latex--label ...>} in order to refer to an existing src block.
However, it is not true.

`org-latex-src-block--engraved', `org-latex-src-block--minted',
and `org-latex-src-block--listings' only produce a label when src block
has a caption.

We should generally not need to put a caption in order to refer to a
source block listing. At least, it does not look like we need it from
https://tex.stackexchange.com/questions/438260/referencing-without-captions-appearing-but-keeping-numbering

Thoughts? Ideas?

> Tested on example below:
> Produced by listing [[IN]].
>
> #+name: OUT
> #+RESULTS: IN
> #+begin_src emacs-lisp :exports code
> 6
> #+end_src
>
> #+header: :wrap "src emacs-lisp :exports code"
> #+name: IN
> #+begin_src emacs-lisp :exports both
> 6
> #+end_src
>
> Listing [[IN]] produces listing [[OUT]].
>
>  From inspecting HTML or LaTeX output using this example
> for the difference between with and without captions it is
> easy to see that only with captions the output is correct.

-- 
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: [BUG] ox-latex produces broken references to src code listings without caption (was: [BUG] org-lint tells to move #+name to wrong place in results block)

[gerard.vermeulen]

On 25.01.2024 13:41, Ihor Radchenko wrote:
> gerard.vermeulen@posteo.net writes:
> 
>> I have found that CAPTION keywords  in the "name-result-example" in 
>> the
>> manual are essential to produce correct links.
> 
> It should not be essential. What you demonstrated is two bugs in Org 
> mode.
> 
>> In case the relevant blocks have e.g. ":exports both", Org handles
>> this, but:
>> 1. HTML export requires captions to produce links with unequivocal
>>     "link texts" which are numbers in the HTML output.
> 
> Fixed, on main.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=ea529007d

I confirm that it is fixed.

> 
>> 2. LaTeX export requires captions to produce captions with labels like
>>     =\caption{\label{path}desc}=.
> 
> `org-latex-link' assumes that it is safe to use
> \ref{<org-latex--label ...>} in order to refer to an existing src 
> block.
> However, it is not true.
> 
> `org-latex-src-block--engraved', `org-latex-src-block--minted',
> and `org-latex-src-block--listings' only produce a label when src block
> has a caption.
> 
> We should generally not need to put a caption in order to refer to a
> source block listing. At least, it does not look like we need it from
> https://tex.stackexchange.com/questions/438260/referencing-without-captions-appearing-but-keeping-numbering
> 
> Thoughts? Ideas?

I do not see how to put the LaTeX hypertarget inside listings where it 
is
needed, because those listings are not floating.

I looked at `org-latex-src-block--verbatim' that uses the LaTeX
captionof macro, by exporting
--- begin narrow lines below ---
#+caption: caption or comment
#+name: name
#+begin_src emacs-lisp
(+ 1 2)
#+end_src

Link \ref{name}.
--- end narrow lines above

But, I cannot get the captionof macro working after:
exporting the snippet above using `org-latex-src-block--listings'
without caption and adding the captionof macro by hand
(LuaLaTeX does not compile).

> 
>> Tested on example below:
>> Produced by listing [[IN]].
>> 
>> #+name: OUT
>> #+RESULTS: IN
>> #+begin_src emacs-lisp :exports code
>> 6
>> #+end_src
>> 
>> #+header: :wrap "src emacs-lisp :exports code"
>> #+name: IN
>> #+begin_src emacs-lisp :exports both
>> 6
>> #+end_src
>> 
>> Listing [[IN]] produces listing [[OUT]].
>> 
>>  From inspecting HTML or LaTeX output using this example
>> for the difference between with and without captions it is
>> easy to see that only with captions the output is correct.

Regards -- Gerard