Enable raw strings in fig.cap field with hash pipe syntax

[baptiste]

With standard chunk options, I can bypass the need to escape all those pesky latex backslashes,

```{r, fig.cap=r"(This is a caption with maths $\int_a^b dx$, unproblematically.)"}
plot(1,1)
```

unfortunately, the same does not work so well with the hash pipe:

```{r}
#| fig.cap: r"(This is a caption with maths $\int_a^b dx$, problematically.)"
plot(1,1)
```

and if I don't use raw strings:

ERROR: YAMLException: unknown escape sequence (theory.qmd, 23:45)
22: ```{r}
23: #| fig.cap: "This is a caption with maths $\int_a^b dx$, problematically."
                                               ~~
24: plot(1,1)

[baptiste]

I'm not too familiar with Quarto's internal toolchain, but considering its language-agnostic philosophy compared to Rmd, I imagine it'd be preferable to have a language-agnostic solution here, i.e. the same raw string syntax valid for any engine, and also for non-computational tables or images.

Perhaps this means introducing a standard notation for raw strings, that allows Quarto to parse such Yaml entries (that are valid Pandoc markdown) without chocking. The same problem happens in the document's Yaml header (LaTeX in title field, etc.), but it's a more obvious problem here, because captions have potentially a lot more content to escape manually).

Pandoc itself doesn't seem to mind unescaped maths in Yaml fields.

[mcanouil]

Thanks for this clarification 😉

[baptiste]

I can see why requiring valid Yaml is convenient from an implementation point of view, but in terms of user experience it's a real inconvenience here. A huge part of the motivation to switch from LaTeX to Rmarkdown and now Quarto is that the syntax is less cumbersome and distracting. Having to escape every backslash in captions of mathematical documents is going to be a real pain point for many users, and it is also unexpected since the main text doesn't have this constraint, and neither does rmarkdown (cf r"()" syntax above.

Since the r"()" syntax already works half-way (doesn't make Yaml return a parsing error, which I find quite mysterious now), maybe this wouldn't be too difficult to implement? (simply check that the string has this special raw string syntax, and treat it accordingly).

[cscheid]

The issue is not r"()", it's the backslash in that string.

And this it's more than an implementation convenience. It's a requirement for a central part of the user experience: autocompletion, validation of the metadata, and documentation all derived from the same source. For better or worse, this tradeoff is here to stay.

[baptiste]

The backslash is actually just fine when I use r"()" (no idea why). I'm happy with the !expr r"()" workaround, which is essentially what knitr's chunk syntax allowed in the first place, but to me it suggests that down the line non-R users will want something similar.

[cscheid]

That's because in YAML there's a difference between "unquoted scalars" and "quoted scalars"

- foo # an unquoted scalar whose value is `foo`
- "foo" # a quoted scalar whose value is `foo`
- r"foo" # an _unquoted_ scalar with quotes in its content whose value is `r"foo"`

Where you need to be careful with backslashes is in quoted scalars, because their behavior in different from that in R, JS, etc. (yes, YAML is annoying like that. It's also the best solution for our usecase.) And yes, !expr is currently an r-specific option; we haven't implemented the generic version because jupyter itself hasn't standardized inline evaluation of code.

[baptiste]

Thankfully, as a R user, I can use the following workaround:

```{r}
#| fig.cap: !expr r"(This is a caption with maths $\int_a^b dx$, problematically.)"
plot(1,1)
```

which evaluates the caption as an R expression, returning a raw string, which is passed as is to pandoc (no need to escape invalid yaml).

From the docs I suspect this is a R-only strategy; I believe it'd be beneficial to have a language-agnostic syntax/convention for passing raw strings.

[baptiste]

Actually, this fails as well when the caption text contains a : , because Yaml assumes it's, well, Yaml ¯_(ツ)_/¯.

So I'm going to keep using the old knitr chunk syntax for the fig.cap field, hoping it doesn't get removed before a more robust solution is implemented.

[cscheid]

You can use colons, but that means that the !expr value needs to be a quoted scalar:

---
title: hello
---

```{r}
#| fig.cap: !expr 'r"(Cap: This is a caption with maths $\int_a^b dx$, problematically.)"'
plot(1,1)
```

[baptiste]

Nice! Thanks, this works well (only gotcha is the need to escape single quotes ' that might appear in the text (by doubling them), but that's not very common.)

[baptiste]

Actually much more common than I foolishly assumed, at least in English –

#| fig-cap: !expr 'r"(There''s no escape from \LaTeX.)"'

So I'm still going to revert to the knitr chunk syntax for this one, hoping it stays.

[baptiste]

It would be nice to have something like Bookdown's Text references for this kind of situation.

A normal paragraph.

(ref:foo) A scatterplot of the data `cars` using **base** R graphics, unescaped \LaTeX.

```{r}
#| fig-cap: '(ref:foo)'
plot(cars)  # a scatterplot
```

[mcanouil]

This (bookdown/ref) has nothing to do with raw R strings or am I missing something?

Note that the ref/bookdown thing has a more general discussion on "complex caption", see #1785 and the issue tracking this #1959

[baptiste]

I hadn't seen the issue and feature request – definitely something that'll come up again and again, so it's good to have cross-links to it here. I approached it from one angle – trying to avoid escaping \ in figure captions, for which raw strings seemed a straight-forward approach – but the more general problem is simply: how does one write complex captions as painlessly as possible (no escaping needed, code evaluation possible, no trickiness with nested double- and single-quotes)? For that more general question, it seems bookdown had introduced a useful construct, and it's on the tracker for quarto.

[mcanouil]

Closing in favour of #4944