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/)]

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/)]

[James Powell]

Using Org mode version 9.4.4 I build this document:

<<begin>>
#+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 |

I want to refer to Table [[t1]].
<<end>>

What I expect: the latex export will include the table and link to it.

What happens instead: the code and table appear, numbered and captioned.
However, the link is broken ("I want to refer to Table ??"). Looking in
the latex, this line reads

 > I want to refer to Table \ref{org993764c}.

but that label org993764c appears nowhere else in the file.

Org-lint doesn't complain about the file at all.  I posted this
earlier to this list and learned about a workaround

" It works if you put a #+label on the table ... which confuses me,
because I looked through the manual for #+label and there's no mention
of it at all, but a bunch of my Org files use it (for LaTeX export). "

(William Denton writing in
https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00170.html)

As another workaround, the snippet as written (with no #+label) works
if you export to html instead of latex.

- JP

---

Emacs  : GNU Emacs 25.3.1 (x86_64-pc-linux-gnu, GTK+ Version 3.24.5)
  of 2020-07-07
Package: Org mode version 9.4.4 (9.4.4-dist @ 
/home/powellj/elisp/org-9.4.4/lisp/)

current state:
==============
(setq
  org-tab-first-hook '(org-babel-hide-result-toggle-maybe 
org-babel-header-arg-expand)
  org-adapt-indentation nil
  org-latex-classes '(("achemso" "\\documentclass{achemso}"
                       ("\\section{%s}" . "\\section*{%s}")
                       ("\\subsection{%s}" . "\\subsection*{%s}")
                       ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
                       ("\\paragraph{%s}" . "\\paragraph*{%s}")
                       ("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
                      ("article" "\\documentclass[11pt]{article}"
                       ("\\section{%s}" . "\\section*{%s}")
                       ("\\subsection{%s}" . "\\subsection*{%s}")
                       ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
                       ("\\paragraph{%s}" . "\\paragraph*{%s}")
                       ("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
                      ("report" "\\documentclass[11pt]{report}"
                       ("\\part{%s}" . "\\part*{%s}")
                       ("\\chapter{%s}" . "\\chapter*{%s}")
                       ("\\section{%s}" . "\\section*{%s}")
                       ("\\subsection{%s}" . "\\subsection*{%s}")
                       ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
                      ("book" "\\documentclass[11pt]{book}"
                       ("\\part{%s}" . "\\part*{%s}")
                       ("\\chapter{%s}" . "\\chapter*{%s}")
                       ("\\section{%s}" . "\\section*{%s}")
                       ("\\subsection{%s}" . "\\subsection*{%s}")
                       ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
                      )
  org-speed-command-hook '(org-speed-command-activate 
org-babel-speed-command-activate)
  org-reverse-note-order t
  org-occur-hook '(org-first-headline-recenter)
  org-metaup-hook '(org-babel-load-in-session-maybe)
  org-agenda-start-on-weekday nil
  org-html-format-drawer-function #[514 "\207" [] 3 "\n\n(fn NAME 
CONTENTS)"]
  org-log-done 'time
  org-latex-format-inlinetask-function 
'org-latex-format-inlinetask-default-function
  org-confirm-shell-link-function 'yes-or-no-p
  org-ascii-format-inlinetask-function 'org-ascii-format-inlinetask-default
  org-startup-folded 'content
  org-agenda-loop-over-headlines-in-active-region nil
  org-link-search-must-match-exact-headline nil
  org-file-apps '(("\\.pdf" . "evince %s") (auto-mode . emacs) 
(directory . emacs)
                  ("\\.mm\\'" . default) ("\\.x?html?\\'" . default)
                  ("\\.pdf\\'" . default))
  org-agenda-skip-scheduled-if-done t
  org-agenda-custom-commands '(("d" todo #("DELEGATED" 0 9 (face 
org-warning)) nil)
                               ("c" todo
                                #("DONE|DEFERRED|CANCELLED" 0 23 (face 
org-warning))
                                nil)
                               ("w" todo #("WAITING" 0 7 (face 
org-warning)) nil)
                               ("W" agenda "" ((org-agenda-ndays 21)))
                               ("A" agenda ""
                                ((org-agenda-skip-function
                                  (lambda nil
                                   (org-agenda-skip-entry-if (quote 
notregexp)
                                    "\\=.*\\[#A\\]")
                                   )
                                  )
                                 (org-agenda-ndays 1)
                                 (org-agenda-overriding-header
                                  "Today's Priority #A tasks: ")
                                 )
                                )
                               ("u" alltodo ""
                                ((org-agenda-skip-function
                                  (lambda nil
                                   (org-agenda-skip-entry-if (quote 
scheduled)
                                    (quote deadline) (quote regexp) 
"<[^>\n]+>")
                                   )
                                  )
                                 (org-agenda-overriding-header
                                  "Unscheduled TODO entries: ")
                                 )
                                )
                               )
  org-latex-format-headline-function 
'org-latex-format-headline-default-function
  org-default-notes-file "~/notes.org"
  org-agenda-include-diary t
  org-latex-format-drawer-function #[514 "\207" [] 3 "\n\n(fn _ CONTENTS)"]
  org-odt-format-headline-function 'org-odt-format-headline-default-function
  org-src-mode-hook '(org-src-babel-configure-edit-buffer
                      org-src-mode-configure-edit-buffer)
  org-agenda-before-write-hook '(org-agenda-add-entry-text)
  org-babel-pre-tangle-hook '(save-buffer)
  org-html-footnotes-section "<div id='footnotes'><!--%s-->%s</div>"
  org-mode-hook '(#[0 "\301\211\x10\207"
                    [imenu-create-index-function org-imenu-get-tree] 2]
                  (lambda nil
                   (define-key org-mode-map (kbd "<f5>") (quote 
org-export-as-pdf)))
                  (lambda nil
                   (if window-system nil
                    (progn (define-key org-mode-map "\212" (quote 
org-meta-return))
                     (define-key org-mode-map "\n"
                      (quote org-insert-heading-respect-content))
                     )
                    )
                   )
                  org-mode-reftex-setup
                  #[0 "\300\301\302\303\304$\207"
                    [add-hook change-major-mode-hook org-show-all append 
local] 5]
                  #[0 "\300\301\302\303\304$\207"
                    [add-hook change-major-mode-hook 
org-babel-show-result-all append
                     local]
                    5]
                  org-babel-result-hide-spec org-babel-hide-all-hashes)
  org-bibtex-headline-format-function #[257 "\300\x01\236A\207" [:title] 3 
"\n\n(fn ENTRY)"]
  org-archive-hook '(org-attach-archive-delete-maybe)
  org-ascii-format-drawer-function #[771 "\x01\207" [] 4 "\n\n(fn NAME 
CONTENTS WIDTH)"]
  org-odt-format-inlinetask-function 
'org-odt-format-inlinetask-default-function
  org-cycle-hook '(org-cycle-hide-archived-subtrees org-cycle-hide-drawers
                   org-cycle-show-empty-lines
                   org-optimize-window-after-visibility-change)
  org-link-shell-confirm-function 'yes-or-no-p
  org-export-before-parsing-hook '(org-attach-expand-links)
  org-todo-keywords '((sequence "TODO(t)" "STARTED(s@/!)" "WAITING(w@/!)"
                       "DELEGATED(e@/!)" "APPT(@!)" "|" "DONE(d!)" 
"DEFERRED"
                       "CANCELLED(c@)")
                      )
  org-fast-tag-selection-single-key 'expert
  org-link-elisp-confirm-function 'yes-or-no-p
  org-confirm-elisp-link-function 'yes-or-no-p
  org-metadown-hook '(org-babel-pop-to-session-maybe)
  org-odt-format-drawer-function #[514 "\207" [] 3 "\n\n(fn NAME CONTENTS)"]
  org-link-from-user-regexp "\\<James Eckhardt Powell\\>"
  org-agenda-skip-deadline-if-done t
  org-html-format-headline-function 
'org-html-format-headline-default-function
  org-link-parameters '(("attachment" :follow org-attach-follow :complete
                         org-attach-complete-link)
                        ("id" :follow org-id-open)
                        ("eww" :follow org-eww-open :store 
org-eww-store-link)
                        ("rmail" :follow org-rmail-open :store 
org-rmail-store-link)
                        ("mhe" :follow org-mhe-open :store 
org-mhe-store-link)
                        ("irc" :follow org-irc-visit :store 
org-irc-store-link :export
                         org-irc-export)
                        ("info" :follow org-info-open :export 
org-info-export :store
                         org-info-store-link)
                        ("gnus" :follow org-gnus-open :store 
org-gnus-store-link)
                        ("docview" :follow org-docview-open :export 
org-docview-export
                         :store org-docview-store-link)
                        ("bibtex" :follow org-bibtex-open :store 
org-bibtex-store-link)
                        ("bbdb" :follow org-bbdb-open :export 
org-bbdb-export
                         :complete org-bbdb-complete-link :store 
org-bbdb-store-link)
                        ("w3m" :store org-w3m-store-link) ("file+sys") 
("file+emacs")
                        ("shell" :follow org-link--open-shell)
                        ("news" :follow
                         #[514 "\301\300\302\x04Q\x02\"\207" ["news" 
browse-url ":"] 6
                           "\n\n(fn URL ARG)"]
                         )
                        ("mailto" :follow
                         #[514 "\301\300\302\x04Q\x02\"\207" ["mailto" 
browse-url ":"] 6
                           "\n\n(fn URL ARG)"]
                         )
                        ("https" :follow
                         #[514 "\301\300\302\x04Q\x02\"\207" ["https" 
browse-url ":"] 6
                           "\n\n(fn URL ARG)"]
                         )
                        ("http" :follow
                         #[514 "\301\300\302\x04Q\x02\"\207" ["http" 
browse-url ":"] 6
                           "\n\n(fn URL ARG)"]
                         )
                        ("ftp" :follow
                         #[514 "\301\300\302\x04Q\x02\"\207" ["ftp" browse-url 
":"] 6
                           "\n\n(fn URL ARG)"]
                         )
                        ("help" :follow org-link--open-help)
                        ("file" :complete org-link-complete-file)
                        ("elisp" :follow org-link--open-elisp)
                        ("doi" :follow org-link--open-doi))
  org-babel-load-languages '((dot . t) (R . t) (shell . t))
  org-html-format-inlinetask-function 
'org-html-format-inlinetask-default-function
  org-agenda-files '("~/jep-files/docs/projects.org" 
"~/jep-files/docs/notes.org"...
  org-clock-out-hook '(org-clock-remove-empty-clock-drawer)
  org-confirm-babel-evaluate nil
  org-publish-project-alist '(("org" :base-directory "~/org/" 
:publishing-directory
                               "~/public_html" :section-numbers nil 
:with-toc nil
                               :publishing-function org-latex-publish-to-pdf
                               :html-head
                               "<link rel=\"stylesheet\"\n 
href=\"../other/mystyle.css\"\n type=\"text/css\"/>")
                              ("2020_MCTD_HDDV_Registration" :base-directory
"~/deq/projects/heavyduty-registration-archive/2020_MCTD_HDDV_Registration" 
:publishing-directory "~/public_html" :publishing-function 
org-latex-publish-to-pdf)
                              )
  )

-- 
James E. Powell, MS
Pronouns: he/him/his
Applied Physics PhD Candidate
Department of Physics
Portland State University
Home page: http://web.pdx.edu/~powellj
Office: SRTC 409B Phone: +1-503-725-8515

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]

Hello,

James Powell <powellj@pdx.edu> writes:

> Using Org mode version 9.4.4 I build this document:
>
> <<begin>>
>
> #+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 |
>
> I want to refer to Table [[t1]].
> <<end>>
>
> What I expect: the latex export will include the table and link to it.
>
> What happens instead: the code and table appear, numbered and captioned.
> However, the link is broken ("I want to refer to Table ??"). Looking in
> the latex, this line reads
>
>  > I want to refer to Table \ref{org993764c}.
>
> but that label org993764c appears nowhere else in the file.
>
> Org-lint doesn't complain about the file at all.  I posted this
> earlier to this list and learned about a workaround
>
> " It works if you put a #+label on the table ... which confuses me,
> because I looked through the manual for #+label and there's no mention
> of it at all, but a bunch of my Org files use it (for LaTeX export). "

#+label is an outdated equivalent for #+name.

In this case, you are referencing the source code block whereas you want
to reference the table. So #+name should go before the table.

Note that if you follow [[t1]] link, point will move to the source code
block, not the table.

Regards,
-- 
Nicolas Goaziou

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/)]

[James Powell]

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

After C-c C-c in the code block, the table appears twice in the org mode 
file:
<<begin>>
#+begin_src R :exports both
   library(tidyverse)
   x <- tribble(~a, ~b, 1, 3)
   x
#+end_src

#+RESULTS:
| 1 | 3 |

#+NAME: t1
#+CAPTION: Org Table
#+RESULTS: t1
| 1 | 3 |

I want to refer to Table [[t1]].
<<end>>

The literature and the Library of Babel do not seem to address the
case, which is so common in peer-reviewed literature, of a captioned
and referenced table that was produced by code.  It was only through a
large investment in trial and error and searching that I was able to
build the example above, in which the code does indeed generate a
table that is captioned and referenced.

- JP

On 4/19/21 10:45 AM, Nicolas Goaziou wrote:
> Hello,
>
> James Powell <powellj@pdx.edu> writes:
>
>> Using Org mode version 9.4.4 I build this document:
>>
>> <<begin>>
>>
>> #+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 |
>>
>> I want to refer to Table [[t1]].
>> <<end>>
>>
>> What I expect: the latex export will include the table and link to it.
>>
>> What happens instead: the code and table appear, numbered and captioned.
>> However, the link is broken ("I want to refer to Table ??"). Looking in
>> the latex, this line reads
>>
>>   > I want to refer to Table \ref{org993764c}.
>>
>> but that label org993764c appears nowhere else in the file.
>>
>> Org-lint doesn't complain about the file at all.  I posted this
>> earlier to this list and learned about a workaround
>>
>> " It works if you put a #+label on the table ... which confuses me,
>> because I looked through the manual for #+label and there's no mention
>> of it at all, but a bunch of my Org files use it (for LaTeX export). "
> #+label is an outdated equivalent for #+name.
>
> In this case, you are referencing the source code block whereas you want
> to reference the table. So #+name should go before the table.
>
> Note that if you follow [[t1]] link, point will move to the source code
> block, not the table.
>
> Regards,

-- 
James E. Powell, MS
Pronouns: he/him/his
Applied Physics PhD Candidate
Department of Physics
Portland State University
Home page: http://web.pdx.edu/~powellj
Office: SRTC 409B Phone: +1-503-725-8515

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]

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