figure divs for pdf format cause LaTeX error

[kbvernon]

Bug description

Sorry if this has already been reported. I did a quick search to check, but didn't see anything...

It looks like Pandoc's div blocks for figures, under certain conditions, generate the LaTeX error - Not in outer par mode.

Here's an example:

---
title: "figure divs"
format: pdf

::: {#fig-quarto}
![](quarto.png){fig-align="center" width="2in"}

Caption here
:::

Here's what I think is the relevant Quarto output during render:

updating tlmgr

updating existing packages

compilation failed- error
LaTeX Error: Not in outer par mode.

A few things to note:

1. This doesn't cause an error for the html format. Everything looks right.
2. If you move the figure options to the div block, as in ::: {#fig-quarto fig-align="center" width="2in"}, the document renders but the figure options are ignored. Is this expected behavior?
3. Inspecting the .tex file, it appears that adding figure options inside the Pandoc div block, as in the example above, causes Quarto to wrap a LaTeX figure environment inside another figure environment (see below). I kinda wonder if this is what's causing the error, but I don't understand LaTeX sufficiently to say.

\begin{figure}
  {\centering 
    \begin{figure}
      {\centering \includegraphics[width=2in,height=\textheight]{quarto.png}}
    \end{figure}
  }
  \caption{\label{fig-quarto}Caption here}
\end{figure}

Here's my system info:

> sessioninfo::session_info()
─ Session info ──────────────────────────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.2.1 (2022-06-23 ucrt)
 os       Windows 10 x64 (build 22621)
 system   x86_64, mingw32
 ui       RStudio
 language (EN)
 collate  English_United States.utf8
 ctype    English_United States.utf8
 tz       America/Denver
 date     2023-01-29
 rstudio  2022.12.0+353 Elsbeth Geranium (desktop)
 pandoc   2.19.2 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)

> quarto::quarto_version()
[1] ‘1.2.329’

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.

[cscheid]

Thanks for the report. Ideally, we'd be more robust in these situations. But I'm wondering if the syntax we recommend in the docs isn't working for you for some reason.

[kbvernon]

Hi, yeah. The standard syntax works:

![Caption here](quarto.png){#fig-quarto fig-align="center" width="2in"}

But, when the caption gets longer, it gets a little unwieldy, especially when you want to include text formatting. I suppose you can do this:

![
This is a __long__ caption with _formatting_.
](quarto.png){fig-align="center" width="2in"}

though the Pandoc div is still easier to read (mainly because you reference the image before the caption, but it can also handle empty lines, too). I guess that's a minor, somewhat nitpicky point, but it's worth noting that the div syntax works as expected for html, so it seems like it should in the pdf case, too. Or, maybe it should? I would defer to you all on this one.

[cscheid]

Eventually we would like to fix things like these, but the fact that this works for HTML is (more or less) a happy accident. The spurious extra div doesn't hurt HTML, but creates a bad scaffolding in .tex that causes the error you're seeing. Leaving this one for the future (it might shake out of some of the changes we're making) but to be honest, there are other matters in the quarto codebase we will want to attend to first.

[desk7]

For now (Quarto 1.3.433), you can use div for single image for pdf and long caption in this way:

::: {#fig-test layout-align="center"}
![](quarto.png){width="2in"}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec in dignissim massa. Sed scelerisque dignissim ipsum, ac suscipit eros sodales ac. Integer congue sem sit amet vestibulum gravida. Pellentesque vestibulum, nibh et aliquam viverra, nunc diam luctus erat, in hendrerit dui mauris id sem. Proin accumsan turpis nec ligula fringilla, vitae congue tortor ultrices. Morbi volutpat, arcu et volutpat facilisis, ipsum nulla suscipit magna, a blandit elit ex sit amet dui. Phasellus finibus augue urna, eget convallis est sollicitudin vitae. Pellentesque sed aliquet mauris. Donec a turpis velit. Morbi interdum bibendum tempor.
:::

In fact, the error is caused by the fig-align="center" attribute in the image.

[cderv]

In fact, the error is caused by the fig-align="center" attribute in the image.

Thanks for the addition ! This is definitely the issue as we are in that case creating two \begin{figure} which leads to the error in LaTeX.

I believe the issue is in that we are processing twice the figure first as a Div and then as a Para when fig-align is set on the figure itself. Code part of Quarto is there.

quarto-cli/src/resources/filters/layout/figures.lua

Lines 6 to 41 in 9c2bcc2

	-- extended figure features including fig-align, fig-env, etc.
	function extended_figures()
	return {
	Para = function(el)
	local image = discoverFigure(el, false)
	if image and shouldHandleExtendedImage(image) then
	if _quarto.format.isHtmlOutput() then
	return htmlImageFigure(image)
	elseif _quarto.format.isLatexOutput() then
	return latexImageFigure(image)
	elseif _quarto.format.isDocxOutput() then
	return wpDivFigure(createFigureDiv(el, image))
	elseif _quarto.format.isAsciiDocOutput() then
	return asciidocFigure(image)
	end
	end
	end,
	Div = function(el)
	if isFigureDiv(el) and shouldHandleExtended(el) then
	if _quarto.format.isLatexOutput() then
	return latexDivFigure(el)
	elseif _quarto.format.isHtmlOutput() then
	return htmlDivFigure(el)
	elseif _quarto.format.isDocxOutput() then
	return wpDivFigure(el)
	elseif _quarto.format.isJatsOutput() then
	return jatsDivFigure(el)
	elseif _quarto.format.isAsciiDocOutput() then
	return asciidocDivFigure(el)
	end
	end
	end
	}
	end

When Div, latexImageFigure() will be called, and then when Para latexImageFigure() will be called.

For each we are creating the logic

\begin{figure}

{\centering 

And nesting this structure is I think not allowed in LaTeX. We should not process the same when extended figures are inside Div IMO. At least in LaTeX.

[cscheid]

This behaves better in the new crossref work, FYI. Keep an eye out for #4944.

[Robinlovelace]

Just to add to this, I found the same error message when I added #| label: ... labels to subfigures, only affecting pdf outputs.

[felipecrp]

Hi, the problem happens with subfigures as well. The following snippet can also reproduce the problem with PDF output:

::: {#fig-basic 
  fig-cap="Caption for fig"
} 

![Caption for a](./figs/a.svg){#fig-basic-a}

![Caption for b](./figs/b.svg){#fig-basic-b}
:::

[felipecrp]

And nesting this structure is I think not allowed in LaTeX. We should not process the same when extended figures are inside Div IMO. At least in LaTeX.

For information and help with the issue solution, we can use Figures and Subfigures in latex. The latex output would be something like this:

\begin{figure}
    \centering
    \begin{subfigure}[b]{\linewidth}
        \centering
        \includegraphics[width=\linewidth]{a.png}
        \caption{}\label{fig:a}
    \end{subfigure}
    \hfill
    \begin{subfigure}[b]{\linewidth}
        \vspace{0.75cm}
        \centering
        \includegraphics[width=\linewidth]{b.png}
        \caption{}\label{fig:b}
    \end{subfigure}
    \hfill
    \caption{}\label{fig:ab}
\end{figure}

[cderv]

@felipecrp this does work when I try latest 1.4

---
title: "Untitled"
format: pdf
---

::: {#fig-basic}

![Caption for a](surus.png){#fig-basic-a}

![Caption for b](surus.png){#fig-basic-b}

Caption for fig
:::

The LaTeX produced is

\begin{figure}

\centering{

\centering{

\includegraphics{surus.png}

}

\subcaption{\label{fig-basic-a}Caption for a}

\centering{

\includegraphics{surus.png}

}

\subcaption{\label{fig-basic-b}Caption for b}

}

\caption{\label{fig-basic}Caption for fig}

\end{figure}%

Please to open a new issue if you have a new issue related to subfigures, and share a reproducible example.

This issue was about fig-align and Figures divs, but I believe this is even fixed.

---
title: "Untitled"
format: pdf
keep-tex: true
---

::: {#fig-basic}

![](surus.png){fig-align='center' width="2in"}

Caption for fig
:::

@cscheid was there anything specific or has this been fixed by the work on Figures for 1.4 ?

[cscheid]

It looks fixed to me. If we can get a new reprex for a specific use case, then we should open a new issue. I'm going to go ahead and close.