Controlling custom crossref caption location with LaTeX

[andrewheiss]

In 1.4.504, with the new custom crossref types, it's possible to control the location of the caption for custom types using a {ref-type_name}-cap-location YAML key (and maybe someday within that custom YAML key #7484 (comment)).

---
title: "Caption location"
crossref:
  custom:
    - kind: float
      prefix: Table S
      space-before-numbering: false
      name: Table S
      ref-type: supptbl
      latex-env: supptbl
      latex-list-of-file-extension: lost
      latex-list-of-description: Supplementary Table
supptbl-cap-location: top
---

See @supptbl-letters:

::: {#supptbl-letters}

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

My Caption

:::

This works fine with HTML:

But this custom caption location does not work with LaTeX output—all custom crossref floats will have their captions appear at the bottom.

That's because Quarto uses the float LaTeX package to create a new custom float environment:

...
\@ifpackageloaded{float}{}{\usepackage{float}}
\floatstyle{plain}
\@ifundefined{c@chapter}{\newfloat{supptbl}{h}{lost}}{\newfloat{supptbl}{h}{lost}[chapter]}
\floatname{supptbl}{Table S}
...

which then gets used later in the document:

\begin{supptbl}

\caption{\label{supptbl-letters}My Caption}

\centering{
...
}

\end{supptbl}

Caption location for that new float is controlled by \floatstyle{}, which is currently hardcoded to be \floatstyle{plain}, so all supptbl captions appear at the bottom.

Fortunately this is fixable by setting a new floatstyle for the custom float like this:

\floatstyle{plaintop}
\restylefloat{supptbl}

That can go either in the preamble or in the body of the document. For instance, this fixes it:

```{=latex}
\floatstyle{plaintop}
\restylefloat{supptbl}
```

See @supptbl-letters:

::: {#supptbl-letters}

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

My Caption

:::

---

idk how the allowed cap-location YAML keys (top, bottom, margin) get translated to LaTeX normally for tables and figures, but it might be nice someday to also translate them to \floatstyle{plaintop} (for "top"), \floatstyle{plain} for "bottom", and whatever magic is used to get floats in the margin for "margin" instead of hardcoding \floatstyle{plaintop} into the preamble.

In the meantime, including this somewhere in the document is a fine workaround:

\floatstyle{plaintop}
\restylefloat{supptbl}

[cscheid]

Thank you. Somehow, for regular table environments, controlling the caption location is done by moving the \caption command around. But as you've seen and taught me, that's not the case for custom float environments (because why would things make sense in LaTeX?) We'll fix this.

I'll tell you another unfortunate thing I just realized, and maybe preempt your next bug report.

Since you're emitting Markdown tables inside custom float environments:

Unfortunately, Pandoc always renders Markdown tables to longtable environments. longtable environments hardcode a float environment and, even more bafflingly, always increment the table counter specifically, also in a hard-coded fashion. In addition, they don't break across multiple pages if they're inside another float environment themselves. We have a hack to roll back the table counter everytime we see a longtable "where it doesn't belong", but we can't fix everything. Fundamentally, we cannot make things work well when there are Markdown tables inside a custom crossref environment: those tables will never break across multiple pages.

[cscheid]

PR is open, but more fixes are needed, because longtable is hell. Your patience is appreciated.

[andrewheiss]

longtable strikes again!

IRL I'm not using md tables in my custom sections (I'm using computational gt/kableExtra tables that can avoid emitting longtable)—that was just for the reprex, and I'd forgotten that pandoc forced everything into longtable! So all is well.

---

Someday it'd be neat if pandoc and all these table-making packages supported tabularray, which apparently is the Cool New Thing for making latex tables that span across tables, merge cells/rows, can have filled content, can deal with line breaks, etc. - there's an issue for that over at pandoc (jgm/pandoc#7475), and apparently some LaTeX incantation to magically convert longtables into tabularrays, but I haven't played with it yet.