*doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

*doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Lin Sun]

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

Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Ihor Radchenko]

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

Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Ihor Radchenko]

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

Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Lin Sun]

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

Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Ihor Radchenko]

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.

Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Lin Sun]

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

Hi Ihor,

Clear! Thank you so much!

Please just ignore this patch, and close this ticket.

B.R.
Lin

[-- Attachment #2: Type: text/html, Size: 1135 bytes --]

Re: *doc/org-manual.org: Fix the description for "Internal Link" in the org-mode manual

[Ihor Radchenko]

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>