Re: Bug: redundant and undocumented #label is required to link to a table [9.4.4 (9.4.4-dist @ /home/powellj/elisp/org-9.4.4/lisp/)]

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

James Powell <powellj@pdx.edu> writes:

> If I put #+name before the table, the link does indeed work, but now
> the table is reproduced twice in the latex output and also C-c C-c in
> the code block writes a new table into the file instead of updating
> the current table.
>
> Before C-c C-c in the code block, this org snippet produces the table 
> twice in the latex output:
> <<begin>>
>
> #+begin_src R :exports both
>    library(tidyverse)
>    x <- tribble(~a, ~b, 1, 3)
>    x
> #+end_src
>
> #+NAME: t1
> #+CAPTION: Org Table
>
> #+RESULTS: t1
> | 1 | 3 |
>
>
> I want to refer to Table [[t1]].
> <<end>>

OK. My explanation was a bit short. Let me expound it a bit.

There are two important keywords in this situation: #+name and
#+results. The former is used to reference a specific element in
a document. The latter is used to know what source code block produced
an element. #+results keywords are automatically generated by Org
whereas #+name keywords are always written by the user.

When you see "#+results: t1" above a table in the previous example, you
and Org know a source block named (with #+name) "t1" generated this
table. Example:

  #+name: some name
  #+begin_src R :exports both
    library(tidyverse)
    x <- tribble(~a, ~b, 1, 3)
    x
  #+end_src

generates

  #+results: some name
  | 1 | 3 |

If you then write "tribble(~a, ~b, 1, 4)" in the source block,
evaluating it again will replace the table because Org knows what table
you are generating:

  #+results: some name
  | 1 | 4 |

Note that since the table itself doesn't have any "#+name", you cannot
reference it with an internal link yet.

Had you seen "#+results:" instead, you would have known that an unnamed
source block, located right above the table, had created the table.
Example:

  #+begin_src R :exports both
    library(tidyverse)
    x <- tribble(~a, ~b, 1, 3)
    x
  #+end_src

  #+results:
  | 1 | 3 |

> After C-c C-c in the code block, the table appears twice in the org mode 
> file:

Let's analyze your document, which I paste here for easier reading:

  #+begin_src R :exports both
    library(tidyverse)
    x <- tribble(~a, ~b, 1, 3)
    x
  #+end_src
  
  #+NAME: t1
  #+CAPTION: Org Table
  #+RESULTS: t1
  | 1 | 3 |

Your source block is now unnamed. Upon evaluating it, Org looks for some
generated structure right below it. Unfortunately, the table below
claims (per #+results keyword) to come from a source block named "t1".
Consequently, it cannot be the output of the code block Org is currently
evaluating, and Org deduces no previous output has been created so far
by the code block: it inserts a new table in the document.

Moreover, an element, here the table, cannot realistically have both
#+name and #+results set to the same value, as it raises a chicken and
egg problem. It is not really an error though.

So, the correct document would be the following:

  #+name: t1
  #+begin_src R :exports both
    library(tidyverse)
    x <- tribble(~a, ~b, 1, 3)
    x
  #+end_src
  
  #+caption: Org Table
  #+results: t1
  | 1 | 3 |

With it, evaluating (with C-c C-c) the source code block will not create
a new table, because references are appropriately set.

If you later want to refer to the table, you can write, e.g.,

  #+name: t1
  #+begin_src R :exports both
    library(tidyverse)
    x <- tribble(~a, ~b, 1, 3)
    x
  #+end_src
  
  #+name: t1_output
  #+caption: Org Table
  #+results: t1
  | 1 | 3 |

so [[t1_output]] links jump to the table.

HTH,
-- 
Nicolas Goaziou