* *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual
@ 2022-06-02 0:16 Lin Sun
2022-06-02 14:15 ` Ihor Radchenko
0 siblings, 1 reply; 7+ messages in thread
From: Lin Sun @ 2022-06-02 0:16 UTC (permalink / raw)
To: emacs-orgmode@gnu.org
[-- Attachment #1.1: Type: text/plain, Size: 571 bytes --]
Hi,
When I try to export follow org document to html, there is an error message: Unable to resolve link: "Test".
The foot script in section "Internal Link" of org-mode manual says:
> When targeting a ‘NAME’ keyword, the ‘CAPTION’ keyword is mandatory in order to get proper numbering
Adding a CAPTION not work, but adding the 'PROPERTY' before name does work.
So the attached patch try to correct the description in the foot script.
#+begin_src python :results table
return 1
#+end_src
#+PROPERTY:
#+NAME: Test
#+RESULTS:
|1|
[[Test]]
[-- Attachment #1.2: Type: text/html, Size: 3006 bytes --]
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-manual-Fix-the-internal-link-document-for-it-depends.patch --]
[-- Type: text/x-patch; name="0001-manual-Fix-the-internal-link-document-for-it-depends.patch", Size: 1165 bytes --]
From 9b473024a5f1e19e00f198d97b1be13789062c82 Mon Sep 17 00:00:00 2001
From: Lin Sun <sunlin7@hotmail.com>
Date: Wed, 1 Jun 2022 00:01:07 +0000
Subject: [PATCH] manual: Fix the internal-link document for it depends on the
PROPERTY
* doc/org-manual.org: The internal-link acctually depends on PROPERTY
than CAPTION
---
doc/org-manual.org | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 9094f81..a2c9df2 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -21922,8 +21922,8 @@ can be used. Just type a star followed by a few optional letters into
the buffer and press {{{kbd(M-TAB)}}}. All headlines in the current
buffer are offered as completions.
-[fn:26] When targeting a =NAME= keyword, the =CAPTION= keyword is
-mandatory in order to get proper numbering (see [[*Captions]]).
+[fn:26] When targeting a =NAME= keyword, the =PROPERTY= keyword is
+mandatory in order to get proper numbering (see [[*Property Syntax]]).
[fn:27] The actual behavior of the search depends on the value of the
variable ~org-link-search-must-match-exact-headline~. If its value is
--
2.7.0
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual
2022-06-02 0:16 *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual Lin Sun
@ 2022-06-02 14:15 ` Ihor Radchenko
2022-06-02 14:32 ` Ihor Radchenko
0 siblings, 1 reply; 7+ messages in thread
From: Ihor Radchenko @ 2022-06-02 14:15 UTC (permalink / raw)
To: Lin Sun; +Cc: emacs-orgmode@gnu.org
Lin Sun <sunlin7@hotmail.com> writes:
> When I try to export follow org document to html, there is an error message: Unable to resolve link: "Test".
>
> The foot script in section "Internal Link" of org-mode manual says:
>
>> When targeting a ‘NAME’ keyword, the ‘CAPTION’ keyword is mandatory in order to get proper numbering
>
> Adding a CAPTION not work, but adding the 'PROPERTY' before name does work.
Confirmed.
This should not happen, AFAIU. Instead of suggesting unintuitive
workarounds in the manual, we need to fix the original problem.
Best,
Ihor
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual
2022-06-02 14:15 ` Ihor Radchenko
@ 2022-06-02 14:32 ` Ihor Radchenko
2022-06-02 16:37 ` Lin Sun
2023-12-24 11:44 ` Ihor Radchenko
0 siblings, 2 replies; 7+ messages in thread
From: Ihor Radchenko @ 2022-06-02 14:32 UTC (permalink / raw)
To: Lin Sun; +Cc: emacs-orgmode@gnu.org
Ihor Radchenko <yantar92@gmail.com> writes:
> This should not happen, AFAIU. Instead of suggesting unintuitive
> workarounds in the manual, we need to fix the original problem.
I looked into this further. Org actually behaves correctly in your
example. Please refer to 16.7 Exporting Code Blocks.
Basically, the default Org behavior when exporting blocks is :export
code. Org removes all the results of evaluation.
If you have
-------------
#+begin_src python :results table
return 1
#+end_src
#+NAME: Test
#+RESULTS:
|1|
[[Test]]
-------------
then Org removes the result on export and you end up with:
-------------
#+begin_src python :results table
return 1
#+end_src
#+NAME: Test
[[Test]]
-------------
The link becomes invalid because the result block disappears and there
will be nothing to refer to.
So, you need to keep in mind that naming source block results is not a
good idea to start with. They are meant to change as you execute the
source block and the fact the your #+name: attribute was not removed
when you execute the code block manually is just a coincidence.
The right way to reference code blocks would be
-------------
#+NAME: Test
#+begin_src python :results table
return 1
#+end_src
#+RESULTS: Test
| 1 |
[[Test]]
-------------
Note that Org automatically assigns the correct name to results. It has
different syntax.
In summary, there is no _bug_ on Org side here. However, the behavior is
indeed not very intuitive. This kind of scenario should probably be
added to org-lint, so that users can be warned about assigning
attributes to src block results.
Best,
Ihor
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual
2022-06-02 14:32 ` Ihor Radchenko
@ 2022-06-02 16:37 ` Lin Sun
2022-06-03 6:13 ` Ihor Radchenko
2023-12-24 11:44 ` Ihor Radchenko
1 sibling, 1 reply; 7+ messages in thread
From: Lin Sun @ 2022-06-02 16:37 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode@gnu.org
[-- Attachment #1: Type: text/plain, Size: 207 bytes --]
Hi Ihor,
Thank you for the investigation, verify insight, I'll avoid this snapshot from my org files.
And changing the "CAPTION" to "PROPERTY" in the foot script, is it correctly? Thanks
B.R.
Lin
[-- Attachment #2: Type: text/html, Size: 1491 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual
2022-06-02 16:37 ` Lin Sun
@ 2022-06-03 6:13 ` Ihor Radchenko
2022-06-03 15:13 ` Lin Sun
0 siblings, 1 reply; 7+ messages in thread
From: Ihor Radchenko @ 2022-06-03 6:13 UTC (permalink / raw)
To: Lin Sun; +Cc: emacs-orgmode@gnu.org
Lin Sun <sunlin7@hotmail.com> writes:
> And changing the "CAPTION" to "PROPERTY" in the foot script, is it correctly? Thanks
Adding PROPERTY works by accident. (I am wondering what is the logic
behind this idea - there is no meaningful semantic meaning for PROPERTY
keyword in this context)
When you have
-------------
#+begin_src python :results table
return 1
#+end_src
#+PROPERTY:
#+NAME: Test
#+RESULTS:
|1|
[[Test]]
-------------
The buffer AST is roughly the following (you can reproduce by calling
M-: (org-element-parse-buffer)):
(org-data (...) ...
(src-block (...))
(keyword (:key "PROPERTY" ...))
(table (:name "Test" :results ""...))
(paragraph (...)
(link (<Test>...))))
When org-babel searches for results of evaluation, it is looking at the
immediate[1] element following the src-block. That element must have
:results property (because of #+RESUTLS: affiliated keyword).
When you add #+PROPERTY: line in front of the results, you are adding a
new keyword element right after the src-block (#+PROPERTY: is not an
allowed affiliated keyword and it is thus recognized as an independent
element). So, when org-babel tries to search and remove the results of
evaluation during export, it is not able to find any because the
following element is just a keyword, not an element with :results
property. Hence, your export appears to be "fixed".
Best,
Ihor
[1] Strictly speaking, not just immediate. When the src-block has :name
property, org-babel searches further for another following element with
the same :results property.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual
2022-06-02 14:32 ` Ihor Radchenko
2022-06-02 16:37 ` Lin Sun
@ 2023-12-24 11:44 ` Ihor Radchenko
1 sibling, 0 replies; 7+ messages in thread
From: Ihor Radchenko @ 2023-12-24 11:44 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Lin Sun, emacs-orgmode@gnu.org
Ihor Radchenko <yantar92@gmail.com> writes:
> In summary, there is no _bug_ on Org side here. However, the behavior is
> indeed not very intuitive. This kind of scenario should probably be
> added to org-lint, so that users can be warned about assigning
> attributes to src block results.
Now, we have org-lint reporting this scenario.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b8b02e3da
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=e9ae9dbc5
--
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] 7+ messages in thread
end of thread, other threads:[~2023-12-24 11:42 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-06-02 0:16 *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual Lin Sun
2022-06-02 14:15 ` Ihor Radchenko
2022-06-02 14:32 ` Ihor Radchenko
2022-06-02 16:37 ` Lin Sun
2022-06-03 6:13 ` Ihor Radchenko
2022-06-03 15:13 ` Lin Sun
2023-12-24 11:44 ` Ihor Radchenko
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).