eval is about expressions, not lines

[fkohrt]

What would you like to do?

Report an issue on quarto.org

Description

The documentation on the eval option currently says the following:

A list of positive or negative line numbers to selectively include or exclude lines (explicit inclusion/excusion of lines is available only when using the knitr engine)

However, this is not correct. Take the following document:

---
title: "Test"
format: html
engine: knitr
---

```{r}
#| eval = -2
if (TRUE) {
  print(1)
  print(2)
}
print(3)
print(4)
```

If the number provided to eval were about lines, then 1 should not get printed. However, it is 3 which does not get printed, because the number provided to eval is about expressions. This is also evident from the corresponding documentation for knitr:

It can also be a numeric vector to choose which R expression(s) to evaluate, e.g., eval = c(1, 3, 4) will evaluate the first, third, and fourth expressions, and eval = -(4:5) will evaluate all expressions except the fourth and fifth.

[cscheid]

There's something weird happening here: eval = 3 is not valid Quarto syntax for configuring options, because it's invalid YAML.

[mcanouil]

@cscheid but that's a valid knitr R multi-line syntax unfortunately.

Knitr allows:

```{r, eval = TRUE}

```{r}
#| eval = TRUE

```{r}
#| eval: true

Note that to be multiple options using the R multi-line syntax you need a trailing comma.

```{r}
#| eval = TRUE,
#| include = FALSE

Luckily, you cannot mix R and YAML multi-line syntaxes.

[fkohrt]

I did not use eval: -2 (in-chunk YAML syntax) because that gets rejected before rendering.

In file test.qmd
(line 8, columns 10--12) Field "eval" has value -2, which must instead be `true` or `false`
7: ```{r}
8: #| eval: -2
           ~~~
9: if (TRUE) {
✖ The value -2 is of type number.
ℹ The error happened in location eval.

ERROR: Validation of YAML cell metadata failed.
ERROR: Render failed due to invalid YAML.

[cscheid]

We should either fix the documentation string to be explicit that Quarto doesn't allow numbers in eval (which I think is the correct approach, because jupyter and julia don't work that way), or we should change the schema to allow it.

Unfortunately, and to add to the complication, we have a limitation where options cannot have different schemas in different engines.

[cderv]

If the number provided to eval were about lines, then 1 should not get printed. However, it is 3 which does not get printed, because the number provided to eval is about expressions. This is also evident from the corresponding documentation for knitr:

@fkohrt yes this is indeed the problem. This was a bad copy past and documented it wrong in the doc.

Unfortunately, and to add to the complication, we have a limitation where options cannot have different schemas in different engines.

@cscheid I think we are hitting this case again. We currently documented the knitr specific option support

quarto-cli/src/resources/schema/cell-codeoutput.yml

Lines 14 to 15 in e8eefd9

	- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines
	(explicit inclusion/excusion of lines is available only when using the knitr engine)

IMO, this should be allowed for backward compatibility with knitr. As long as we support quarto render *.Rmd, this should work.

And even with not considering Rmd doc support, this is a feature of the knitr engine that should be available to users.

This is same problem in a way than

• try to add duplicate warning definition only for knitr #11875

as echo and eval are used in cell, but can also be defined globally in document execute.

Anyhow, first step is to fix the doc even in the current situation.