search

quarto-dev / quarto-cli

Open-source scientific and technical publishing system built on Pandoc.
https://quarto.org
Other
3.76k stars 306 forks source link

LaTeX - Floats defined by `newfloat` don't support subfloats: listings, custom crossrefs, etc. #9455

Open LuckeyBertl28 opened 4 months ago

LuckeyBertl28 commented 4 months ago

Bug description

Issue: Sublistings Failing to Render in PDF Output

When attempting to render a Quarto document to PDF, sublistings are not being supported. The error varies depending on whether the listings option is enabled or disabled.

I have expected to work the same way as figures.

It works as expected for the HTML output.

Possible Solution

Additional Notes

The expected functionality was assumed to be analogous to that of figures within the document. However, due to my limited knowledge in Quarto, LaTeX, and Lua, I am not able to provide a more comprehensive solution.

Steps to reproduce

---
title: Sublistings Issue
format: 
    pdf:
        listings: true
        keep-tex: true
---

:::: {#lst-multiple-listings}

::: {#lst-foo}
```{.json}
{
    "test": "foo"
}

Foo :::

::: {#lst-bar}

{
    "test": "bar"
}

Bar :::

::::

Referencing listing group @lst-multiple-listings.

Referencing sublistings @lst-foo, @lst-bar.


### Expected behavior

The document should render to PDF without any errors, supporting sublistings similar to how sub-figures are handled.

### Actual behavior

### When `listings: true` 

[sublistings_issue_listings_true.log](https://github.com/quarto-dev/quarto-cli/files/15075048/sublistings_issue_listings_true.log)

```bash
quarto render sublistings_issue.qmd 
pandoc 
  to: latex
  output-file: sublistings_issue.tex
  standalone: true
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  listings: true

metadata
  documentclass: scrartcl
  classoption:
    - DIV=11
    - numbers=noendperiod
  papersize: letter
  header-includes:
    - '\KOMAoption{captions}{tableheading}'
  block-headings: true
  title: Sublistings Issue

Rendering PDF
running xelatex - 1
  This is XeTeX, Version 3.141592653-2.6-0.999996 (TeX Live 2024) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode

updating tlmgr

updating existing packages
ERROR: 
compilation failed- error
LaTeX Error: Environment codelisting undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.149 \begin{codelisting}

see sublistings_issue.log for more information.
ERROR: Error
    at renderFiles (file:///opt/quarto/bin/quarto.js:77074:29)
    at eventLoopTick (ext:core/01_core.js:183:11)
    at async render (file:///opt/quarto/bin/quarto.js:81807:21)
    at async Command.fn (file:///opt/quarto/bin/quarto.js:81954:32)
    at async Command.execute (file:///opt/quarto/bin/quarto.js:8104:13)
    at async quarto (file:///opt/quarto/bin/quarto.js:114968:5)
    at async file:///opt/quarto/bin/quarto.js:114986:9

When listings: false

sublistings_issue_listings_false.log

quarto render sublistings_issue.qmd 
pandoc 
  to: latex
  output-file: sublistings_issue.tex
  standalone: true
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  listings: false

metadata
  documentclass: scrartcl
  classoption:
    - DIV=11
    - numbers=noendperiod
  papersize: letter
  header-includes:
    - '\KOMAoption{captions}{tableheading}'
  block-headings: true
  title: Sublistings Issue

Rendering PDF
running xelatex - 1
  This is XeTeX, Version 3.141592653-2.6-0.999996 (TeX Live 2024) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode

updating tlmgr

updating existing packages
ERROR: 
compilation failed- error
Package caption Error: Undefined counter `subcodelisting'.

See the caption package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.194 \subcaption
                 {\label{lst-foo}Foo} 

see sublistings_issue.log for more information.
ERROR: Error
    at renderFiles (file:///opt/quarto/bin/quarto.js:77074:29)
    at eventLoopTick (ext:core/01_core.js:183:11)
    at async render (file:///opt/quarto/bin/quarto.js:81807:21)
    at async Command.fn (file:///opt/quarto/bin/quarto.js:81954:32)
    at async Command.execute (file:///opt/quarto/bin/quarto.js:8104:13)
    at async quarto (file:///opt/quarto/bin/quarto.js:114968:5)
    at async file:///opt/quarto/bin/quarto.js:114986:9

Rendering to HTML

Rendering to HTML works without errors, output looks as expected.

quarto render sublistings_issue.qmd --to html
pandoc 
  to: html
  output-file: sublistings_issue.html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png

metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  title: Sublistings Issue

Output created: sublistings_issue.html

Your environment

Quarto check output

quarto check
Quarto 1.4.549
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.4.549
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2024.03.13
      Chromium: 869685

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /home/bertlluk/.TinyTeX/bin/x86_64-linux
      Version: 2024

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.8.10
      Path: /usr/bin/python3
      Jupyter: 5.3.0
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/
cscheid commented 4 months ago

Unfortunately, I think we cannot support the listings: true option in crossreferenceable Quarto listings (those that have ids lst-*). Specifically, the issue is that Quarto uses its own float environment and crossref counters. listings: true is a pandoc option that enables the listings LaTeX package. However, the listings documentation doesn't seem to show any way to change which float environment is used by listings, nor does it seem to support sublistings.

LuckeyBertl28 commented 4 months ago

I've noticed that the error doesn't seem to be associated with the listings: true option, as a different error occurs when listings: false is set.

To elaborate, when I include the following include-in-header in the configuration:

format: 
    pdf:
        listings: true
        include-in-header:
            - text: |
                \newenvironment{codelisting}{\begin{figure}}{\end{figure}}

the document renders correctly. The listings are captioned as Figure because that’s how I’ve defined them. However, I propose replacing the figure environment in the code snippet above with the environment that Quarto typically uses for listings.

In the generated TeX file sublistings_issue.tex.txt, you’ll notice that the listings are encapsulated within the codelisting environment (see lines 150, 184). This issue isn’t related to the listings package since the codelisting environment isn’t predefined, leading to the error. Once I manually define the environment, the rendering works as intended. However, I’m unsure how to configure the codelisting environment to match the one Quarto typically utilizes for listings.

cscheid commented 4 months ago

However, I propose replacing the figure environment in the code snippet above with the environment that Quarto typically uses for listings.

That won't work. We already use a float environment defined by newfloat, using the float package. The bug here is that it seems that the float package simply doesn't support subfloats (in the way expected by \subcaption). Replacing codelisting with figure works because figure is defined by a different environment that does support subfloat counters for \subcaption.

Unfortunately, there isn't much we can do here in the short term.