Internal link to resulting image from source block

Internal link to resulting image from source block

[reza]

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

Hi List

I'm exporting a plantuml figure to HTML like

#+name: html transformation
#+begin_src plantuml :file img/transformation-html.svg :exports results
   file org
   file html
   org -> html : org-html-publish-to-html
#+end_src

Now I want to include an internal link to this figure with ~[[html 
transformation]]~ but when I export I always get "Unable to resolve 
link". Any idea what I'm doing wrong?

Thanks for any help.

Cheers Reza

[-- Attachment #2: OpenPGP_0xC375C6AF05125C52.asc --]
[-- Type: application/pgp-keys, Size: 15557 bytes --]

[-- Attachment #3: OpenPGP_signature --]
[-- Type: application/pgp-signature, Size: 499 bytes --]

Re: Internal link to resulting image from source block

[Ihor Radchenko]

reza <reza@housseini.me> writes:

> Hi List
>
> I'm exporting a plantuml figure to HTML like
>
> #+name: html transformation
> #+begin_src plantuml :file img/transformation-html.svg :exports results
>    file org
>    file html
>    org -> html : org-html-publish-to-html
> #+end_src
>
> Now I want to include an internal link to this figure with ~[[html 
> transformation]]~ but when I export I always get "Unable to resolve 
> link". Any idea what I'm doing wrong?

Nothing really wrong on your side. It is probably an omission on the Org
side.

Executing the above code produces

#+RESULTS: html transformation
[[file:img/transformation-html.svg]]

However, it is currently impossible to link to such results paragraph by
itself - only to the parent src block. Since you are using :exports
results, the export code does not "see" the src block; only the results
block which cannot be referenced. Hence, the error.

They way to work around the problem is providing explicit name anchor to
the results block:

------------
#+name: html transformation
#+begin_src plantuml :file img/transformation-html.svg :exports results :mkdirp yes
   file org
   file html
   org -> html : org-html-publish-to-html
#+end_src

#+name: html transformation result
#+RESULTS: html transformation
[[file:img/transformation-html.svg]]

Now I want to include an internal link to this figure with [[html
transformation result]]. This works now.
------------

Though I do agree that the current behaviour is not intuitive in this
specific scenario. When a user provides :exports results, it would make
sense to inherit all the affiliated keywords, including #+name and
possibly various #+attr_* to the results of evaluation.

On the other hand, inheriting may be tricky. I can imagine situations
when such inheritance is not desired and a user actually prefers to
state the results keywords manually.

I am not sure what would be the best way to handle the situation at hand
while not breaking the other :exports variants.

Best,
Ihor

Re: Internal link to resulting image from source block

[reza]

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

On 8/4/22 04:37, Ihor Radchenko wrote:
> 
> Nothing really wrong on your side. It is probably an omission on the Org
> sid >
> Executing the above code produces
> 
> #+RESULTS: html transformation
> [[file:img/transformation-html.svg]]
> 
> However, it is currently impossible to link to such results paragraph by
> itself - only to the parent src block. Since you are using :exports
> results, the export code does not "see" the src block; only the results
> block which cannot be referenced. Hence, the error.

I assumed it was something like this, but thank you for the clarification.
> They way to work around the problem is providing explicit name anchor to
> the results block:
> 
> ------------
> #+name: html transformation
> #+begin_src plantuml :file img/transformation-html.svg :exports results :mkdirp yes
>     file org
>     file html
>     org -> html : org-html-publish-to-html
> #+end_src
> 
> #+name: html transformation result
> #+RESULTS: html transformation
> [[file:img/transformation-html.svg]]
> 
> Now I want to include an internal link to this figure with [[html
> transformation result]]. This works now.
> ------------
> 
> Though I do agree that the current behaviour is not intuitive in this
> specific scenario. When a user provides :exports results, it would make
> sense to inherit all the affiliated keywords, including #+name and
> possibly various #+attr_* to the results of evaluation.
> 
> On the other hand, inheriting may be tricky. I can imagine situations
> when such inheritance is not desired and a user actually prefers to
> state the results keywords manually.
> 
> I am not sure what would be the best way to handle the situation at hand
> while not breaking the other :exports variants.

Shall I file a bug report? As a beginner I assumed that the name tag 
gets carried over to the result and I still think it is a sensible 
solution, but I could imagine that is perhaps not a very explicit behavior.

Cheers,
Reza

[-- Attachment #2: OpenPGP_0xC375C6AF05125C52.asc --]
[-- Type: application/pgp-keys, Size: 15557 bytes --]

[-- Attachment #3: OpenPGP_signature --]
[-- Type: application/pgp-signature, Size: 499 bytes --]

Re: Internal link to resulting image from source block

[Ihor Radchenko]

reza <reza@housseini.me> writes:

>> They way to work around the problem is providing explicit name anchor to
>> the results block:
>> 
>> ------------
>> #+name: html transformation
>> #+begin_src plantuml :file img/transformation-html.svg :exports results :mkdirp yes
>>     file org
>>     file html
>>     org -> html : org-html-publish-to-html
>> #+end_src
>> 
>> #+name: html transformation result
>> #+RESULTS: html transformation
>> [[file:img/transformation-html.svg]]
>> 
>> Now I want to include an internal link to this figure with [[html
>> transformation result]]. This works now.
>> ------------
>> 
>> Though I do agree that the current behaviour is not intuitive in this
>> specific scenario. When a user provides :exports results, it would make
>> sense to inherit all the affiliated keywords, including #+name and
>> possibly various #+attr_* to the results of evaluation.
>> 
>> On the other hand, inheriting may be tricky. I can imagine situations
>> when such inheritance is not desired and a user actually prefers to
>> state the results keywords manually.
>> 
>> I am not sure what would be the best way to handle the situation at hand
>> while not breaking the other :exports variants.
>
> Shall I file a bug report? As a beginner I assumed that the name tag 
> gets carried over to the result and I still think it is a sensible 
> solution, but I could imagine that is perhaps not a very explicit behavior.

This email is already a bug report :)

However, we cannot just blindly carry over the name tag to the result.

Consider a case when you have ":results both" in your src block. Where
should the [[html transformation]] link refer to? The src block? The
resulting image?

Best,
Ihor

Re: Internal link to resulting image from source block

[reza]

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

On 8/5/22 03:48, Ihor Radchenko wrote:
> 
> This email is already a bug report :)
Haha nice :)
> 
> However, we cannot just blindly carry over the name tag to the result.
> 
> Consider a case when you have ":results both" in your src block. Where
> should the [[html transformation]] link refer to? The src block? The
> resulting image?
> 
Perhaps it is sufficient to add a hint to the error message:

unable to resolve link, name tag is on source but you specified :exports 
results

Or just carry it over for :exports results only?

WDYT?


[-- Attachment #2: OpenPGP_0xC375C6AF05125C52.asc --]
[-- Type: application/pgp-keys, Size: 15557 bytes --]

[-- Attachment #3: OpenPGP_signature --]
[-- Type: application/pgp-signature, Size: 499 bytes --]

[PATCH] org-export: Make results of named code blocks a valid link

[Ihor Radchenko]

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

reza <reza@housseini.me> writes:

> On 8/5/22 03:48, Ihor Radchenko wrote:
>> 
>> This email is already a bug report :)
> Haha nice :)
>> 
>> However, we cannot just blindly carry over the name tag to the result.
>> 
>> Consider a case when you have ":results both" in your src block. Where
>> should the [[html transformation]] link refer to? The src block? The
>> resulting image?
>> 
> Perhaps it is sufficient to add a hint to the error message:
>
> unable to resolve link, name tag is on source but you specified :exports 
> results

This would be tricky. The export code is only presented with buffer
version to be exported. All the :exports none/:exports results code
blocks are removed when we resolve links.

> Or just carry it over for :exports results only?

I like this idea better. See the attached patch.
After the patch, links to :exports both blocks will be ambiguous, unless
the results are explicitly named. So, I documented this detail in the
manual.

Let me know if there are any objections.

Best,
Ihor


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-export-Make-results-of-named-code-blocks-a-valid.patch --]
[-- Type: text/x-patch, Size: 4093 bytes --]

From 0a0dda33cee7355602feb954e0645ed8652e0983 Mon Sep 17 00:00:00 2001
Message-Id: <0a0dda33cee7355602feb954e0645ed8652e0983.1659694297.git.yantar92@gmail.com>
From: Ihor Radchenko <yantar92@gmail.com>
Date: Fri, 5 Aug 2022 18:09:02 +0800
Subject: [PATCH] org-export: Make results of named code blocks a valid link
 target

* lisp/ox.el (org-export-search-cells): Use #+RESULTS keyword as
search cell when #+NAME is not provided.  Update the docstring
accordingly.
(org-export-resolve-fuzzy-link): Update the docstring.

* doc/org-manual.org (Exporting Code Blocks): Document the new
behavior and explain the details of exporting links to named code
blocks/results.

Fixes https://orgmode.org/list/010201826cb68597-bf75d596-7890-4dd0-b9ff-0c7b617b4dd4-000000@eu-west-1.amazonses.com
---
 doc/org-manual.org | 30 ++++++++++++++++++++++++++++++
 lisp/ox.el         | 10 ++++++----
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 466718e6e..e03fd059a 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18283,6 +18283,36 @@ ** Exporting Code Blocks
   exported file.  Whether the code is evaluated at all depends on
   other options.  Example: =:exports none=.
 
+If a source block is named using =NAME= keyword, the same name will be
+assigned to the results of evaluation.  This way, fuzzy links pointing
+to the named source blocks exported using =:exports results= will
+remain valid and point to the results of evaluation.
+
+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.
+
+: #+NAME: code name
+: #+BEGIN_SRC emacs-lisp :exports both value
+: (+ 1 2)
+: #+END_SRC
+:
+: #+NAME: results name
+: #+RESULTS: code name
+: 3
+:
+: This [[code name][link]] will point to the code 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
+arbitrarily point either to the code block or to its results when
+results do not have a distinct name.
+
+Note that all the links pointing to a source block exported using
+=:exports none= will be broken.  This will make export process fail,
+unless broken links are allowed during export (see [[*Export Settings]]). 
+
 #+vindex: org-export-use-babel
 To stop Org from evaluating code blocks to speed exports, use the
 header argument =:eval never-export= (see [[*Evaluating Code Blocks]]).
diff --git a/lisp/ox.el b/lisp/ox.el
index 57d375b35..433272915 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -4312,7 +4312,7 @@ (defun org-export-search-cells (datum)
     - target's or radio-target's name as a list of strings if
       TYPE is `target'.
 
-    - NAME affiliated keyword if TYPE is `other'.
+    - NAME or RESULTS affiliated keyword if TYPE is `other'.
 
 A search cell is the internal representation of a fuzzy link.  It
 ignores white spaces and statistics cookies, if applicable."
@@ -4330,7 +4330,8 @@ (defun org-export-search-cells (datum)
 		(and custom-id (cons 'custom-id custom-id)))))))
     (`target
      (list (cons 'target (split-string (org-element-property :value datum)))))
-    ((and (let name (org-element-property :name datum))
+    ((and (let name (or (org-element-property :name datum)
+                        (car (org-element-property :results datum))))
 	  (guard name))
      (list (cons 'other (split-string name))))
     (_ nil)))
@@ -4362,8 +4363,9 @@ (defun org-export-resolve-fuzzy-link (link info &rest pseudo-types)
 
 - If LINK path matches a target object (i.e. <<path>>) return it.
 
-- If LINK path exactly matches the name affiliated keyword
-  (i.e. #+NAME: path) of an element, return that element.
+- If LINK path exactly matches the name or results affiliated keyword
+  (i.e. #+NAME: path or #+RESULTS: name) of an element, return that
+  element.
 
 - If LINK path exactly matches any headline name, return that
   element.
-- 
2.35.1

Re: [PATCH] org-export: Make results of named code blocks a valid link

[reza]

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

On 8/5/22 12:15, Ihor Radchenko wrote:
> I like this idea better. See the attached patch.
> After the patch, links to :exports both blocks will be ambiguous, unless
> the results are explicitly named. So, I documented this detail in the
> manual.

Looks good for me!

Sorry for my ignorance, I thought org-mode is part of Emacs but it seems 
development happens in a separate repo. How is org-mode "added" to Emacs 
because I was a little bit stuck in applying the patch?

Cheers Reza


[-- Attachment #2: OpenPGP_0xC375C6AF05125C52.asc --]
[-- Type: application/pgp-keys, Size: 15557 bytes --]

[-- Attachment #3: OpenPGP_signature --]
[-- Type: application/pgp-signature, Size: 499 bytes --]

Re: [PATCH] org-export: Make results of named code blocks a valid link

[Ihor Radchenko]

reza <reza@housseini.me> writes:

> Sorry for my ignorance, I thought org-mode is part of Emacs but it seems 
> development happens in a separate repo. How is org-mode "added" to Emacs 
> because I was a little bit stuck in applying the patch?

Org mode is distributed with Emacs. However, we only put the latest
stable Org version when Emacs releases.

Because Emacs development is quite slow, Org chose to do the main
development in a separate repo and release on ELPA between Emacs major
releases. See more details in https://orgmode.org/,
https://orgmode.org/worg/org-contribute.html, and
https://orgmode.org/worg/org-maintenance.html

-- 
Ihor Radchenko,
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] org-export: Make results of named code blocks a valid link

[Ihor Radchenko]

Ihor Radchenko <yantar92@gmail.com> writes:

>> Or just carry it over for :exports results only?
>
> I like this idea better. See the attached patch.
> After the patch, links to :exports both blocks will be ambiguous, unless
> the results are explicitly named. So, I documented this detail in the
> manual.

Applied onto main via 5184c4382.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=5184c4382da171fe5f451694251a0e28c24f4d98

-- 
Ihor Radchenko,
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