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

[Ihor Radchenko]

Ihor Radchenko  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 .
Support Org development at ,
or support my work at 

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

[Lin Sun]

Hi Ihor,

Clear! Thank you so much!

Please just ignore this patch, and close this ticket.

B.R.
Lin

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

[Ihor Radchenko]

Lin Sun  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 (...

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]

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

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

[Ihor Radchenko]

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

[Ihor Radchenko]

Lin Sun  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