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

[gerard.vermeulen@posteo.net]

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