TOC of tables for org-mode long tables

Question

Here is a super-short org mode file ready to export to pdf C-c C-e l o. It is a sample file to demonstrate long tables and the issue I am facing with the auto generated index of tables by org-mode.

#+TITLE: Testing out =longtable=

# below gets rid of the red boxes drawn around the links
# `hyperref' package is already included in org-latex-default-packages-alist
#+LaTeX_HEADER: \hypersetup{
#+LaTeX_HEADER:     colorlinks,%
#+LaTeX_HEADER:     citecolor=black,%
#+LaTeX_HEADER:     filecolor=black,%
#+LaTeX_HEADER:     linkcolor=blue,%
#+LaTeX_HEADER:     urlcolor=blue
#+LaTeX_HEADER: }

#+TOC: tables

#+CAPTION: This is a long table
#+ATTR_LaTeX: :environment longtable
#+NAME: tab:longtable
|----------+----------|
| Header 1 | Header 2 |
|----------+----------|
|        1 | Item 1   |
|        2 | Item 2   |
|        3 | Item 3   |
|        4 | Item 4   |
|        5 | Item 5   |
|        6 | Item 6   |
|        7 | Item 7   |
|        8 | Item 8   |
|        9 | Item 9   |
|       10 | Item 10  |
|       11 | Item 11  |
|       12 | Item 12  |
|       13 | Item 13  |
|       14 | Item 14  |
|       15 | Item 15  |
|       16 | Item 16  |
|       17 | Item 17  |
|       18 | Item 18  |
|       19 | Item 19  |
|       20 | Item 20  |
|       21 | Item 21  |
|       22 | Item 22  |
|       23 | Item 23  |
|       24 | Item 24  |
|       25 | Item 25  |
|----------+----------|

Using latex specific attributes, I am specifying org-mode to use the longtable latex package for creating that table.

The table renders fine, but the issue is that for each page the long table spans, an extra entry is created in the TOC for tables. The below example is short, but if I have a table spanning 5 pages, 5 entries are created in the TOC with the same table title!

Below screenshots show the 2 pdf pages:

How can I make org-mode put only one TOC entry per table (and not per table per page)?

Answer 1

Interesting, that's almost equally a LaTeX question.

According to the longtable documentation, the correct way to discriminate the first chunk of the table is to use \endfirsthead

Therefore you can get the effect you want by adding the following LaTeX attribute:

#+ATTR_LaTeX: :caption \caption{\label{tab:longtable}This is a long table}\\\hline Header 1 & Header 2\\\hline\endfirsthead

Of course this forces you to handle the caption yourself, so you need to make sure that the \label{} in that fragment keeps in sync with the org attribute #+NAME. I guess a macro could help if that's an issue.

Ideally, we'd like the generated code look like that:

\begin{longtable}{rl}
\\
\caption[]{This is a long table}\\
\hline
Header 1 & Header 2\\
\hline
\endhead
\caption{\label{tab:longtable}This is a long table}\\
\hline
Header 1 & Header 2\\
\hline
\endfirsthead
\hline\multicolumn{2}{r}{Continued on next page} \\
\endfoot
\endlastfoot
1 & Item 1\\
...
25 & Item 25\\
\hline
\end{longtable}

But it appears the code to handle the table and caption (org-latex--org-tabl) and the code to handle the rows (org-latex-table-row) are sufficiently disjoint that it would require some significant refactoring to allow for that kind of code generation.

That said, I strongly suspect that it should be an option (if not the default) option to avoid multiplying entries in the list of tables. So maybe opening a bug report would be the best course of action

Answer 2

Thanks to @Sigma's answer, I found a temporary workable solution till org-mode supports this in a cleaner way.

The below solution could have looked prettier were it not for the below shown org-mode macro limitations:

Unable to have nested macro replacement. The below is not possible.

#+MACRO: LT_REF     ref_longtable
#+MACRO: LT_TITLE   This is a long table
#+MACRO: LT_HEADER1 Header 1 
#+MACRO: LT_HEADER2 Header 2
{{{LT_HEADER({{{LT_REF}}}, {{{LT_TITLE}}}, {{{LT_HEADER1}}}, {{{LT_HEADER2}}})}}}

Unable to use macros in #+NAME:. The below is not possible.

#+NAME: {{{LT_REF}}}

Due to these limitations, the table reference tag and the headers have to be manually repeated.

My solution derived from @Sigma's answer:

#+TITLE: Testing out =longtable=

# below gets rid of the red boxes drawn around the links
# `hyperref' package is already included in org-latex-default-packages-alist
#+LaTeX_HEADER: \hypersetup{
#+LaTeX_HEADER:     colorlinks,%
#+LaTeX_HEADER:     citecolor=black,%
#+LaTeX_HEADER:     filecolor=black,%
#+LaTeX_HEADER:     linkcolor=blue,%
#+LaTeX_HEADER:     urlcolor=blue
#+LaTeX_HEADER: }

#+MACRO: LT_HEADER #+ATTR_LaTeX: :caption \caption{\label{$1} $2}\\\hline $3 & $4 \\\hline\endfirsthead\caption[]{$2}\endhead

#+TOC: tables

#+ATTR_LaTeX: :environment longtable
{{{LT_HEADER(ref_longtable, This is a long table, Header 1, Header 2)}}}
#+NAME: ref_longtable
|----------+----------|
| Header 1 | Header 2 |
|----------+----------|
|        1 | Item 1   |
|        2 | Item 2   |
|        3 | Item 3   |
|        4 | Item 4   |
|        5 | Item 5   |
|        6 | Item 6   |
|        7 | Item 7   |
|        8 | Item 8   |
|        9 | Item 9   |
|       10 | Item 10  |
|       11 | Item 11  |
|       12 | Item 12  |
|       13 | Item 13  |
|       14 | Item 14  |
|       15 | Item 15  |
|       16 | Item 16  |
|       17 | Item 17  |
|       18 | Item 18  |
|       19 | Item 19  |
|       20 | Item 20  |
|       21 | Item 21  |
|       22 | Item 22  |
|       23 | Item 23  |
|       24 | Item 24  |
|       25 | Item 25  |
|----------+----------|

NOTE: There MUST be NO space in the \label{LABEL} section. I had hard time debugging why the tex to pdf conversion wasn't able to resolve the table references. I had \label{ LABEL } instead of \label{LABEL}.

Answer 3

In org-mode version 8.3+

The minimal working example in the question generates the List of Tables fine without duplication of the table captions when the table is split across pages.

The hack suggested in the above answer is required only for org-mode versions 8.2 or lower.