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