Executable code listing

[cadojo]

Is there any way to produce an executable code listing?

"""
Calculate the ballistic coefficient, β.
"""
β(m, Cᵣ, Aₛ) = m / (Cᵣ * Aₛ)

"""
Calculate the derivative of the downrange distance, ḋ.
"""
ḋ(ν, γ) = ν * cos(γ)

"""
Calculate the terminal velocity, vₜ.
"""
terminal(g, β, ρ, γ) = √(-2g * β * sin(γ) / ρ)

"""
Calculate the maximum deceleration, nₘ.
"""
deceleration(vₑ, γ, hₛ, e) = (vₑ^2 / hₛ) * (sin(γ) / 2e)

[mcanouil]

It's unclear to me what you want to achieve and how the content you shared intervene in the process, could you clarify?

[cadojo]

Yes! Sorry for the late reply. There are two ways to show source code in a Quarto document.

1. Display the code as a code listing
2. Echo an executable block of code

I'd like to set echo: true, and also set label: lst-my-code so the executable code block is cross-reference-able.

```{python}
#| echo: true
#| output: false
#| label: lst-my-code
#| lst-cap: This is a caption for my code!
def f(x,y):
  return x ** 2 + (y - 4)

We can already do something similar with output figures. If executable code generates a figure, we can specify fig-label and fig-cap within an executable code block. Is there a way to show code as a listing in a document, but also execute the code in the listing?

[cscheid]

Not yet. The easiest approach will be to repeat the code in a code listing (https://quarto.org/docs/authoring/cross-references.html#code-listings) and then execute it with echo: false and output: false

[baptiste]

With R/knitr, you can refer to previous chunks with <<chunkname>>, so that would help avoid duplication:

---
title: "Untitled"
format: html
editor: source
---

```{r two}
#| echo: true
#| eval: false
1 + 1
```

reused in the following

```{r}
#| echo: false
#| eval: true
<<two>>
```

not sure if there's an equivalent mechanism for jupyter engines.

However, adding a label reference such as #| label: lst-two seems to break things for some reason.

[mcanouil]

I would suggest to use the Rmarkdown/Quarto syntax rather than the Sweave syntax or a mix of those for code chunk reuse.

---
title: "Untitled"
format: html
editor: source
---

```{r}
#| echo: true
#| eval: false
#| label: two
1 + 1
```

reused in the following

```{r}
#| echo: false
#| eval: true
#| ref.label: two
```

[cderv]

FWIW

• the <<chunkname>> is completely valid and help insert a chunk content inside another code chunk code content.
• ref.label is useful and to be use when this is the whole code chunks that needs to be reuse (e.g with different options)
  • Reusing the same label also works by the way. ref.label is useful for vector of label (so reuse several chunks)

Docs in https://bookdown.org/yihui/rmarkdown-cookbook/reuse-chunks.html

Just adding for reference for anyone finding this thread

[mcanouil]

I am completing my answer with a working workaround using knitr as the engine.

---
title: "Demo"
format: html
---

```{r}
#| echo: true
#| eval: false
#| label: label-for-reuse
#| attr-source: '#lst-label-cross-reference lst-cap="Sum of one and one"'
1 + 1
```

reused code from @lst-label-cross-reference in the following

```{r}
#| echo: false
#| eval: true
#| ref.label: label-for-reuse
```

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

```{python}
#| echo: true
#| eval: false
#| attr-source: '#lst-label-cross-reference lst-cap="What my code is about."'
def f(x,y):
  return x ** 2 + (y - 4)
```

The code from @lst-label-cross-reference do an amazing job.

@cscheid I noticed two lst- options for code cells (knitr/observable/jupyter), but it does not seem to work. Is it a bug or a work in progress thing?

[cadojo]

I think this would be a really useful feature, particularly for book authors who want to be able to cross-reference executable code blocks. Is this a feature that may be supported in the future, or is this known to be not supported?

[cscheid]

I will say that this feature (executable code listings whose inputs can be referenceable) is very much not guaranteed to land in 1.4.

For non-executable artifacts, the situation is simple: the label refers to the artifact itself. This works for listings as well as figures, tables, etc, which is how we support it.

But for executable code listings, there's a problem. The label becomes ambiguous: should it refer to the input code listing, or to the output produced? In executable code cells, the labels have so far always referred to the output. This means that if someone writes label: lst-foo, we no longer know whether you want the input to be the thing that gets lst-foo, or the generated output. This problem becomes even more acute in 1.4, where users will have the ability to pick whatever "type" of crossreference they prefer (eg so that images can be referenced as tables should you choose to have an image of a table).

We haven't been able to come up with a solution that we believe is clean enough for us to adopt, so I'm relatively pessimistic regarding this one specifically.

[baptiste]

Is the 'not clean enough' problem in the implementation? From a user's perspective, I imagine most people would be satisfied with a simple convention such as label: lst-foo refers to the output as usual, while label: lst-foo-input refers to the input (auto-generated, and only available for executable chunks).

[cscheid]

Thanks for the suggestion, but suffixes introduce their own problems - I'm not willing to introduce the additional ambiguity of having to now disallow *-input as a label by itself. Otherwise, is lst-input an input or output? And how would you tell? The problem is sort of fundamentally unsolvable: we either need to

• do in-band signalling of some kind to introduce a new "subspace" for the labels of an input. As a consequence, some previously-valid labels becomes invalid (breakage always bad), and we have a feature that's hard to learn (implicit, auto-generated labels are easy to specify but hard for people to remember, especially in contrast to our typical preference of explicit declarations)
• Or we do out-of-band signalling (eg lst-label: lst-foo) , which means that executable code listings look fundamentally different from non-executable code listings. This is bad, because it makes people want to try fig-label, which won't work, and so will require people to always remember that listings are special.

So, the feature is possible, but my current estimation is that it will make quarto worse than if the feature didn't exist.

[baptiste]

Thanks for the explanation. I wonder if allowing

label: 
  - lst-foo
  - lst-foo-input

or, in one line

label: [lst-foo, lst-foo-input]

would be a workable approach. The default situation is to just have one value, referring to the output, but if the user wants to refer to the input as well, they need to provide a second label, which they define explicitly.

[mcanouil]

The solution proposed earlier in the thread is already a working solution for users that want this (#3626 (comment)).

I strongly agree with the "do not add reserved suffixes" as users get already bitten by the cross-reference prefix.
Also multiple labels for "one" element really is something that should not be implemented in my opinion.

[cadojo]

Thanks for the suggestion, but suffixes introduce their own problems - I'm not willing to introduce the additional ambiguity of having to now disallow *-input as a label by itself. Otherwise, is lst-input an input or output? And how would you tell? The problem is sort of fundamentally unsolvable: we either need to

• do in-band signalling of some kind to introduce a new "subspace" for the labels of an input. As a consequence, some previously-valid labels becomes invalid (breakage always bad), and we have a feature that's hard to learn (implicit, auto-generated labels are easy to specify but hard for people to remember, especially in contrast to our typical preference of explicit declarations)
• Or we do out-of-band signalling (eg lst-label: lst-foo) , which means that executable code listings look fundamentally different from non-executable code listings. This is bad, because it makes people want to try fig-label, which won't work, and so will require people to always remember that listings are special.

So, the feature is possible, but my current estimation is that it will make quarto worse than if the feature didn't exist.

I'm just a user, but providing both code listings, and outputs, feels like a really important feature for textbook authors, etc. Executable code blocks are shown when echo: true. Is there a way to specify a "special case" exclusively for this purpose? Something like echo-label: lst-blah-blah-blah?