* [BUG] org-lint tells to move #+name to wrong place in results block
@ 2024-01-22 17:47 gerard.vermeulen
2024-01-22 18:15 ` Ihor Radchenko
0 siblings, 1 reply; 9+ messages in thread
From: gerard.vermeulen @ 2024-01-22 17:47 UTC (permalink / raw)
To: Emacs orgmode
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [BUG] org-lint tells to move #+name to wrong place in results block
2024-01-22 17:47 [BUG] org-lint tells to move #+name to wrong place in results block gerard.vermeulen
@ 2024-01-22 18:15 ` Ihor Radchenko
2024-01-22 18:50 ` gerard.vermeulen
0 siblings, 1 reply; 9+ messages in thread
From: Ihor Radchenko @ 2024-01-22 18:15 UTC (permalink / raw)
To: gerard.vermeulen; +Cc: Emacs orgmode
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [BUG] org-lint tells to move #+name to wrong place in results block
2024-01-22 18:15 ` Ihor Radchenko
@ 2024-01-22 18:50 ` gerard.vermeulen
2024-01-22 18:59 ` Ihor Radchenko
0 siblings, 1 reply; 9+ messages in thread
From: gerard.vermeulen @ 2024-01-22 18:50 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Emacs orgmode
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [BUG] org-lint tells to move #+name to wrong place in results block
2024-01-22 18:50 ` gerard.vermeulen
@ 2024-01-22 18:59 ` Ihor Radchenko
2024-01-23 8:34 ` [PATCH] Make an org-lint warning more helpful gerard.vermeulen
2024-01-23 13:55 ` [BUG] org-lint tells to move #+name to wrong place in results block gerard.vermeulen
0 siblings, 2 replies; 9+ messages in thread
From: Ihor Radchenko @ 2024-01-22 18:59 UTC (permalink / raw)
To: gerard.vermeulen; +Cc: Emacs orgmode
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Make an org-lint warning more helpful
2024-01-22 18:59 ` Ihor Radchenko
@ 2024-01-23 8:34 ` gerard.vermeulen
2024-01-24 15:49 ` Ihor Radchenko
2024-01-23 13:55 ` [BUG] org-lint tells to move #+name to wrong place in results block gerard.vermeulen
1 sibling, 1 reply; 9+ messages in thread
From: gerard.vermeulen @ 2024-01-23 8:34 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Emacs orgmode
[-- 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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [BUG] org-lint tells to move #+name to wrong place in results block
2024-01-22 18:59 ` Ihor Radchenko
2024-01-23 8:34 ` [PATCH] Make an org-lint warning more helpful gerard.vermeulen
@ 2024-01-23 13:55 ` gerard.vermeulen
2024-01-25 12:41 ` [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
1 sibling, 1 reply; 9+ messages in thread
From: gerard.vermeulen @ 2024-01-23 13:55 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Emacs orgmode
[-- 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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] Make an org-lint warning more helpful
2024-01-23 8:34 ` [PATCH] Make an org-lint warning more helpful gerard.vermeulen
@ 2024-01-24 15:49 ` Ihor Radchenko
0 siblings, 0 replies; 9+ messages in thread
From: Ihor Radchenko @ 2024-01-24 15:49 UTC (permalink / raw)
To: gerard.vermeulen; +Cc: Emacs orgmode
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* [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)
2024-01-23 13:55 ` [BUG] org-lint tells to move #+name to wrong place in results block gerard.vermeulen
@ 2024-01-25 12:41 ` Ihor Radchenko
2024-01-26 11:04 ` gerard.vermeulen
0 siblings, 1 reply; 9+ messages in thread
From: Ihor Radchenko @ 2024-01-25 12:41 UTC (permalink / raw)
To: gerard.vermeulen, Juan Manuel Macías,
Pedro Andres Aranda Gutierrez, Timothy
Cc: Emacs orgmode
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* 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)
2024-01-25 12:41 ` [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
@ 2024-01-26 11:04 ` gerard.vermeulen
0 siblings, 0 replies; 9+ messages in thread
From: gerard.vermeulen @ 2024-01-26 11:04 UTC (permalink / raw)
To: Ihor Radchenko
Cc: Juan Manuel Macías, Pedro Andres Aranda Gutierrez, Timothy,
Emacs orgmode
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
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2024-01-26 11:05 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-01-22 17:47 [BUG] org-lint tells to move #+name to wrong place in results block gerard.vermeulen
2024-01-22 18:15 ` Ihor Radchenko
2024-01-22 18:50 ` gerard.vermeulen
2024-01-22 18:59 ` Ihor Radchenko
2024-01-23 8:34 ` [PATCH] Make an org-lint warning more helpful gerard.vermeulen
2024-01-24 15:49 ` Ihor Radchenko
2024-01-23 13:55 ` [BUG] org-lint tells to move #+name to wrong place in results block gerard.vermeulen
2024-01-25 12:41 ` [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
2024-01-26 11:04 ` gerard.vermeulen
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).