From: gerard.vermeulen@posteo.net
To: Ihor Radchenko <yantar92@posteo.net>
Cc: Emacs orgmode <emacs-orgmode@gnu.org>
Subject: Re: [BUG] org-lint tells to move #+name to wrong place in results block
Date: Tue, 23 Jan 2024 13:55:09 +0000 [thread overview]
Message-ID: <7bf1f79071a714750634e76130fe5963@posteo.net> (raw)
In-Reply-To: <8734upry70.fsf@localhost>
[-- 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
next prev parent reply other threads:[~2024-01-23 13:56 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` gerard.vermeulen [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7bf1f79071a714750634e76130fe5963@posteo.net \
--to=gerard.vermeulen@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).