Link references are wrongly created from R code chunk in included Rmd

[cderv]

While looking at another issue, I found out that when using @includeRmd, the content is processed to deal with link references.

roxygen2/R/rd-include-rmd.R

Lines 64 to 68 in 76ebaab

	rmd_linkrefs_from_file <- function(path) {
	lines <- read_lines(path)
	txt <- paste(lines, collapse = "\n")
	paste(get_md_linkrefs(txt), collapse = "\n")
	}

All the content is read then get_md_linkrefs() applied. This does not take into account the differences between markdown content, and R (or other language) content in code chunks. This leads to weird situation where a link reference is created for some R code.

Real example is with recipes in the file man/rmd/recipes.Rmd
https://github.com/tidymodels/recipes/blob/5cf1ca55217950df54c2bdef2c6de42dab7d6d7f/man/rmd/recipes.Rmd#L47-L49
It contains some R code chunk with this code:

biomass_tr <- biomass[biomass$dataset == "Training",]
biomass_te <- biomass[biomass$dataset == "Testing",]

which is wrongly identified as a link by get_md_linkrefs() . I got this reprex to illustrate

tmp <- tempfile(fileext = ".Rmd")
xfun::write_utf8(c(
  "Some content", 
  "", 
  "```{r}", 
  'biomass_tr <- biomass[biomass$dataset == "Training",]', "```"
), tmp)

# R code is targeted as possible link references
roxygen2:::rmd_linkrefs_from_file(tmp)
#> [1] "[biomass$dataset == \"Training\",]: R:biomass$dataset%20==%20%22Training%22,"

# Seems like this R code match one of the regex
roxygen2:::get_md_linkrefs('biomass_tr <- biomass[biomass$dataset == "Training",]')
#> [1] "[biomass$dataset == \"Training\",]: R:biomass$dataset%20==%20%22Training%22,"

^{Created on 2022-03-24 by the reprex package (v2.0.1)}

Side effect of this is that

[biomass$dataset == \"Training\",]: R:biomass$dataset%20==%20%22Training%22,

is appended by roxy_tag_rd.roxy_tag_includeRmd() to the end of the Rmd file to render. However, it does not make sense as this is not a markdown reference but R code.
As the inserted line as two unescaped $, Pandoc identifies this as Math and try to process. Before Pandoc 2.15, it was silently ignoring as not real math, but since Pandoc 2.15, it creates a warning and an issue when rendering. This is linked to the math issues reported in the context of #1306 and #1304 and I believe this is the source of the remaining issues reported for recipes.

Current workaround is switching to using Pandoc 2.14.2 - no more errors.

Either regex in get_md_linkrefs() should be tweaked, or lines within R code chunk ignored somehow in rmd_linkrefs_from_file().

[gaborcsardi]

Yeah, we if the output is "github_document" then we could parse it as markdown, as usual, and then we would not use the link regex on the code chunks. I think that's probably the right thing to do.

I can do this for the upcoming roxygen2 release. It would be great to fix the outstanding roxygen2 + rmarkdown issues for that.

[cderv]

It would be great to fix the outstanding roxygen2 + rmarkdown issues for that.

What issue is left to fix after this one ? Do we have other improvement in mind like ability to generate Rd compatible math maybe ?

Happy to help for the next release to make rmarkdown + roxygen2 experience better.

[gaborcsardi]

There is at least this issue, and it would be great to support chunk options (https://github.com/r-lib/roxygen2/compare/feature/knitr-chunk-options) and I also want to look at whether we can generate HTML formulas with the katex package, optionally.

[cderv]

I also want to look at whether we can generate HTML formulas with the katex package, optionally.

I was planning to experiment with that. I'll share results.