Code Annotation Blocks Generation of Code Appendix

[neilhatfield]

Bug description

A common tool for creating reproducible documents via R Markdown and Quarto is to include the following to auto generate a code appendix.

# Code Appendix
```{r, ref.label=knitr::all_labels(),echo=TRUE,eval=FALSE}
```

However, when you use even a single code annotation (e.g., # <1>) in any code block, the generation of the code appendix fails. There are no warnings or errors displayed but the code appendix is blank.

Steps to reproduce

---
title: "test"
date-modified: now
latex-tinytex: false
format: pdf
---

## Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

## Running Code

When you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this:

```{r}
1 + 1 # <1>

1. Test statement You can add options to executable code like this

#| echo: false
2 * 2

The echo: false option disables the printing of code (only output is displayed).

Code Appendix

Expected behavior

annotationIssues_expected.pdf

### Actual behavior

[annotationIssues.pdf](https://github.com/quarto-dev/quarto-cli/files/12744761/annotationIssues.pdf)

### Your environment

R version 4.3.1 (2023-06-16) Platform: x86_64-apple-darwin20 (64-bit) Running under: macOS Monterey 12.6.9

### Quarto check output

neilhatfield$ quarto check

[✓] Checking versions of quarto binary dependencies... Pandoc version 3.1.1: OK Dart Sass version 1.55.0: OK [✓] Checking versions of quarto dependencies......OK [✓] Checking Quarto installation......OK Version: 1.3.353 Path: /Applications/RStudio.app/Contents/Resources/app/quarto/bin

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

[✓] Checking Python 3 installation....OK Version: 3.11.1 Path: /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 Jupyter: (None)

  Jupyter is not available in this Python installation.
  Install with python3 -m pip install jupyter

[✓] Checking R installation...........OK Version: 4.3.1 Path: /Library/Frameworks/R.framework/Resources LibPaths:

• /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library knitr: 1.44 rmarkdown: 2.25

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

[mcanouil]

Thanks for the report, could you properly format your post?

You can share a Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).

````qmd
---
title: "Reproducible Quarto Document"
format: html
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)

The end.

---

Assuming up to date version of knitr, the following should work. Note that, I don't think there is a bug per se as it's knitr that tries to aggregate code cells and the annotation feature.

## Code Appendix

```{r}
#| echo: true
#| eval: false
#| ref-label: !expr knitr::all_labels()
#| code-annotations: false

[cderv]

@neilhatfield thanks for the report. BTW I edited your post for readibility. Please next time follow the guideline as reminded in previous reply above.

It seems to be working ok for HTML

However for PDF I indeed see an annotation still in the output for appendix

So I believe this is the issue you are referring. I'll look into the difference between formats.

BTW @mcanouil setting #| code-annotations: false does not help with this as this is not something you can set at a chunk level. It is only a configuration at the document level.

[mcanouil]

Hum, should the users be allowed to disable code annotation on a per chunk basis or modify its behaviour? 🤔 (cc. @dragonstyle)

[cderv]

There should not be annotation shown in output if no list item below the chunk I think. Which seems to be what is happening in HTML. So possible LaTeX has a bug.

Though we could probably add an attributes (and so a cell options) to deactivate code-annotation. Though this should be pretty rare case where you add some #<1> syntax in some cells but don't want annotation for that cell. Do you think this will happen often ?

[neilhatfield]

@cderv I ran a test on switching the output format to HTML on the same machine and the Code Appendix does not generate for me.

[mcanouil]

@neilhatfield You should update your Quarto version at least to the latest stable version which is 1.3.450 (not 1.3.353).

There should not be annotation shown in output if no list item below the chunk I think.

@cderv It's the "I think" that troubles me a bit^^ It seems to be an implicit deactivation while I personally prefer explicit setup in most cases (even if it means more typing, etc.)

[cderv]

It seems to be an implicit deactivation while I personally prefer explicit setup in most cases (even if it means more typing, etc.)

@mcanouil It is not an implicit deactivation. This is a safety measure I would say to strip #<1> in code chunk when annotation are not really correct under cells. At least I see HTML behave that way but It could be a bug - So I understand your point and I'll check that in our code.

What is for sure is that we don't offer opt-in / opt-out on code cells basis. This is document configuration. Either for some reason or just because we did not thing the feature of per-cell config would be that useful.

I know I fixed some problem with code annotations and LaTeX, so I'll check all that because I may have missed something.

If you think code-annotations at per-cell basis is a useful feature, please do open a feature request, and we can consider it if this is feasible (not all our configuration can be targeted at cell level unfortunately without big change in our code)

I ran a test on switching the output format to HTML on the same machine and the Code Appendix does not generate for me.

@neilhatfield You can see on the screenshot above (https://github.com/quarto-dev/quarto-cli/issues/7053#issuecomment-1738906945) that it works with latest Quarto and Latest knitr. So please do check the version .

I just switched YAML header in your example to

---
title: "test"
format: html
---

to make it works.

[neilhatfield]

@mcanouil @cderv I updated Quarto 1.3.450 and tested again with HTML--still no generation of the code appendix. I have version 1.44 of the knitr package installed which is showing as current on CRAN. Is there some other potential configuration issue between your machine and mine? My RStudio version is 2023.06.1+524. I see that there is a recent update online for RStudio (hasn't triggered an update message in RStudio, even when I click Check for Updates).

Edit: I just updated RStudio to 2023.09.0+463 and re-ran on HTML. No dice.

If I remove the code annotation, I get the appendix:

[cderv]

Yes you need latest pre-release 1.4 as we fixed several issues with knitr option handling and also code annotations https://quarto.org/docs/download/prerelease.html

That is the difference - I can reproduce your issue with 1.3.450

[neilhatfield]

@cderv I had an opportunity to install the pre-release build. I was able to now get the code appendix to generate in both HTML and PDF settings, which is an improvement. I do see the annotation marker in the code appendix for PDF output, just as you observed earlier. Thank you for digging in to this.

[cderv]

This is a smaller reprex

---
title: "test"
format: 
  pdf: default
  html: default
keep-md: true
---

This is a code block with annotation but not list below. What should be the behavior ? 

```r
1 + 1 # <1>

<table>
<tr>
 <td>HTML
 <td>PDF
<tr>
 <td>

![image](https://github.com/quarto-dev/quarto-cli/assets/6791940/897ec7cd-dd73-4b79-828c-96ae2527590a)

 <td>

![image](https://github.com/quarto-dev/quarto-cli/assets/6791940/2d5edd98-1042-4922-9f5a-79c4119ce63a)

</table>

I believe this is because in Lua we do stip annotation for HTML and then put back based on matched number

For LaTeX we currently don't strip be leave a comment that we match in Regex later on (after Lua) as LaTeX postprocessing to add the special circle command. 

I believe we should make the behavior consistent

[cderv]

This is more complex than I thought; I don't think our Lua code part for this allow to support LaTeX stripping easy enough. It requires a bit of a redesign. Probably something for 1.5

Possibly having a way to opt-out code annotation at the cell level would help here... 🤔 Maybe easier to add