quarto-dev / quarto-dev/quarto-cli

Support Pandoc's .float table class to avoid longtable in twocolumn layouts

Open
#14,846 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

crossref enhancement latex tables
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

Pandoc's longtable (the default table environment for LaTeX output) is incompatible with twocolumn documents. This has come up before, #3314 for example, and again in a recent discussion comment:

https://github.com/orgs/quarto-dev/discussions/11669#discussioncomment-17905332

Pandoc has now added a way to opt a table out of longtable into a regular floating table environment instead. From the pandoc commit:

LaTeX writer: Provide a way to use table instead of longtable.

When the `float` class is attached to a table, a standard
floating `table` will be generated instead of a `longtable`.
Placement can be specified via the `latex-placement` attribute.
This will help, especially, those who use two-column layouts,
since `longtable` is incompatible with these.

And from the issue comment suggesting the workaround:

function Table(el)
  el.classes:insert("float")
  return el
end

This lands in Pandoc 3.10.1. We currently bundle 3.10,

https://github.com/quarto-dev/quarto-cli/blob/f01c303d1205c1b541fbe0181c8cdb23add388b0/configuration#L16

so it's not usable yet, but we could test it now with QUARTO_PANDOC=<path-to-3.10.1-build>.

If we want to auto-apply the .float class for twocolumn documents, so users don't have to write the Lua filter themselves, the scope isn't as simple as it looks.

For plain, uncaptioned tables (the case in #3314 and the discussion), the Table node reaches Pandoc's LaTeX writer unmodified, we only wrap a table into our own FloatRefTarget custom node when it carries a tbl- label:

https://github.com/quarto-dev/quarto-cli/blob/f01c303d1205c1b541fbe0181c8cdb23add388b0/src/resources/filters/quarto-pre/parsefiguredivs.lua#L524-L560

For those, adding .float when classoption contains twocolumn should be straightforward, we already parse classoption the same way for booksidedness:

https://github.com/quarto-dev/quarto-cli/blob/f01c303d1205c1b541fbe0181c8cdb23add388b0/src/resources/filters/layout/meta.lua#L219-L229

Cross-referenced tables (tbl- label) are more involved. We manually decrement LaTeX's table counter after every longtable, because longtable increments it in a way that double-counts against our own numbering:

https://github.com/quarto-dev/quarto-cli/blob/f01c303d1205c1b541fbe0181c8cdb23add388b0/src/resources/filters/quarto-post/latex.lua#L295-L322

A regular floating table environment is expected to increment that counter, so switching the underlying environment there would make the decrement wrong. There's also raw-text parsing of \begin{longtable}...\end{longtable} for subtable/panel-layout fixups in floatreftarget.lua that assumes longtable specifically:

https://github.com/quarto-dev/quarto-cli/blob/f01c303d1205c1b541fbe0181c8cdb23add388b0/src/resources/filters/customnodes/floatreftarget.lua#L442-L490

So a first version could be scoped to plain tables only, leaving tbl- labeled tables on the longtable path for now.

I haven't tested any of this against an actual 3.10.1 build yet, this is source-reading only.

Related: #3314, #14741 (different bug, same area of code)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by testing Quarto with a Pandoc 3.10.1 build via QUARTO_PANDOC, then read parsefiguredivs.lua and meta.lua to trace plain table handling and twocolumn detection. Review latex.lua and floatreftarget.lua before changing scope; done means plain, uncaptioned tables in twocolumn documents use the floating table path while tbl- labeled tables retain their existing behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, lua
Domain
cli, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.