How to set ''crossref-resolve-refs' to false in quarto markdown.

[phongphuhanam]

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/4722

^{Originally posted by **phongphuhanam** March 9, 2023} Hello, I'm using quarto to create the PDF with all the tables in LaTex format. I also need to create a docx version to share with my colleagues. As I want to cross-ref on both PDF and docx documents, I use the quarto crossref syntax (@tab-). It works fine with docx format, but for PDF I have to manually set ```param("crossref-resolve-refs", true)``` to ```param("crossref-resolve-refs", false)``` in this file [ref.lua](https://github.com/quarto-dev/quarto-cli/blob/4c629a87596818b268ff424d663fd8b0ab3c5bb2/src/resources/filters/crossref/refs.lua#L27). I want to set 'crossref-resolve-refs' to false for PDF output in quarto markdown but I couldn't find any way to do so on the Quarto website. Is there such an option exist? I tried the below setup but it did not work: ```yaml format: pdf: crossref-resolve-refs : false ```

[cderv]

This is an internal configuration that you can't set from YAML for now.

Why do you need to change this value. Can you share a reproducible example of what you want to do ?

This would give us exactly the context of what you are trying to do to aim docx and pdf.

The current crossref system work for Both PDF and docx already, so I am missing what the issue is really that lead to this config being required. Example

---
title: "Tables"
format: 
  pdf: default
  docx: default
---

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

: My Caption {#tbl-letters}

See @tbl-letters.

This will work in PDF and in DOCX

[phongphuhanam]

Thank you for answering my question. My main target document is PDF, and I used the pandas to_latex function to generate the table in LaTEX format. Since pandas markdown table generation lacks some features compared to the latex one, I converted the table in LaTEX format back to markdown. Finally, I used Quarto conditional format to render the same table in different environments.

For examples:

---
title: Test
format:
  pdf:
    keep-tex: true
    pdf-engine-opt: -synctex=1
    pdf-engine: pdflatex
    default-image-extension: pdf
  html:
    # define default configuration for the html version of your format
    number-sections: true
    toc: true
    toc-location: left
    default-image-extension: png
    theme:
      light: flatly
      dark: darkly
  docx: 
    toc: true
---

# Introduction

::: {.content-visible when-format="pdf"}
\begin{table}[ht]
\centering
\footnotesize
\begin{tabular}{ccc}
\toprule
Symbol & Description & Scope \\
\midrule
${I}$ & Image frames & Local\\
\bottomrule
\end{tabular}
\caption{Notation used throughout the paper.}
\label{tbl-notion}
\end{table}
:::

::: {.content-visible unless-format="pdf"}

  Symbol             Description             Scope
--------------- ------------------------- ----------------
      ${I}$            Image frames             Local

: Notation used throughout the paper. {#tbl-notion}

:::

@tbl-notion summarizes the notation used in this paper. 

if I don't manually change the crossref-resolve-refs to false, this example works for docx and html but not pdf.

[cderv]

Oh interesting !

You are outputing different version of table depending on the format.

• raw LaTeX table when pdf
• Markdown table when not pdf.

You have an issue here because when using a non-pdf format you are benefiting from crossref Quarto system, but when using raw LaTeX you are currently not using a syntax that is catched by Quarto. The issue you encounter is :

• @tbl-notion is processed by Quarto and the ref is tried to be resolved
• But tbl-notion reference does not exist for Quarto when PDF as the reference is not seen in the raw LaTeX table.

We are parsing the raw LaTeX table, but the syntax is not the one expected. This is why you are looking for deactivating the crossref for PDF output.

Note that using this syntax will work

::: {.content-visible when-format="pdf"}
\begin{table}[ht]
\centering
\footnotesize
\begin{tabular}{ccc}
\toprule
Symbol & Description & Scope \\
\midrule
${I}$ & Image frames & Local\\
\bottomrule
\end{tabular}
\caption{Notation used throughout the paper.{#tbl-notion}}
\end{table}
:::

Not the {#tbl-notion} in the caption (and no label needed). This w

Don't know if you can add that to your to_latex call in Pandas.

@cscheid I am seing we don't really document what needs to be in the caption when using raw LaTeX table. Did I missed the page ? Is the above the correct way of doing it ? If so, we should maybe document this somewhere.

And also Is there anything that should be done to improve this somehow in your 1.4 crossref overhaul ?

thanks

[cscheid]

Yeah, there's a limited amount we can do in general when a package emits raw latex. We try to detect common patterns, but we can't figure out every way in which other code emits tables.

This is a big motivation for the 1.4 crossref overhaul that I'm about to start work on.

[cderv]

This is a big motivation for the 1.4 crossref overhaul that I'm about to start work on.

Awesome - wasn't sure raw latex was in the scope.

We'll probably update documentation after that thanks!

[phongphuhanam]

Oh interesting !

You are outputing different version of table depending on the format.

• raw LaTeX table when pdf
• Markdown table when not pdf.

You have an issue here because when using a non-pdf format you are benefiting from crossref Quarto system, but when using raw LaTeX you are currently not using a syntax that is catched by Quarto. The issue you encounter is :

• @tbl-notion is processed by Quarto and the ref is tried to be resolved
• But tbl-notion reference does not exist for Quarto when PDF as the reference is not seen in the raw LaTeX table.

We are parsing the raw LaTeX table, but the syntax is not the one expected. This is why you are looking for deactivating the crossref for PDF output.

Note that using this syntax will work

::: {.content-visible when-format="pdf"}
\begin{table}[ht]
\centering
\footnotesize
\begin{tabular}{ccc}
\toprule
Symbol & Description & Scope \\
\midrule
${I}$ & Image frames & Local\\
\bottomrule
\end{tabular}
\caption{Notation used throughout the paper.{#tbl-notion}}
\end{table}
:::

Not the {#tbl-notion} in the caption (and no label needed). This w

Don't know if you can add that to your to_latex call in Pandas.

@cscheid I am seing we don't really document what needs to be in the caption when using raw LaTeX table. Did I missed the page ? Is the above the correct way of doing it ? If so, we should maybe document this somewhere.

And also Is there anything that should be done to improve this somehow in your 1.4 crossref overhaul ?

thanks

@cderv That works well in my case. Thanks a lot. I think the cross-reference section on the Quarto website should be updated with this trick for the raw latex tables.

[cscheid]

This now works on main. The general pattern is to create the crossreferenceable div as a pure-quarto feature, then create arbitrary content for it, and let the different formats render things as they know how to.

---
title: Test
format:
  pdf: default
  html:
    # define default configuration for the html version of your format
    number-sections: true
    toc: true
    toc-location: left
    default-image-extension: png
  docx: 
    toc: true
keep-tex: true
---

# Introduction

::: {#tbl-notion}

::: {}

::: {.content-visible when-format="pdf"}
\begin{tabular}{ccc}
\toprule
Symbol & Description & Scope \\
\midrule
${I}$ & Image frames & Local\\
\bottomrule
\end{tabular}
:::

::: {.content-visible unless-format="pdf"}

  Symbol             Description             Scope
--------------- ------------------------- ----------------
      ${I}$            Image frames             Local

:::

:::

Notation used throughout the paper.

:::

@tbl-notion summarizes the notation used in this paper.