Lost braces

[bastistician]

Markdown mode in roxygen2 does not escape braces and this seems to be intended:

roxygen2/tests/testthat/test-markdown-link.R

Lines 61 to 62 in 47e1c76

	# Non code parts are not escaped (invalid Rd)
	expect_equal(markdown("[foo({ bar })][x]"), "\\link[=x]{foo({ bar })}")

However, many developers don't know that braces need to be escaped in LaTeX-like text in Rd. For example, Rd authors commonly use markup like \pkg{pkgname}, but I have seen markdown-type documentation with roxygen2 using the {pkgname} notation to refer to an R package, where these braces are expected to appear in the rendered documentation. This won't happen, unfortunately:

library("roxygen2")
out <- roc_proc_text(rd_roclet(), "
  #' {pkgname}: Playing with Braces
  #'
  #' Plain-text math: integer in {1, 2, ..., n}, (-1)^{n-1}
  #' @md
  null <- function () NULL
")[[1]]

out
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{null}
#> \alias{null}
#> \title{{pkgname}: Playing with Braces}
#> \usage{
#> null()
#> }
#> \description{
#> Plain-text math: integer in {1, 2, ..., n}, (-1)^{n-1}
#> }

rdfile <- tempfile()
cat(out$format(), file = rdfile)
tools::Rd2txt(rdfile)
#> pkgname: Playing with Braces
#> 
#> Description:
#> 
#>      Plain-text math: integer in 1, 2, ..., n, (-1)^n-1
#> 
#> Usage:
#> 
#>      null()
#> 

tools::checkRd(rdfile)
#> checkRd: (-3) file2c241344a233:5: Lost braces
#>      5 | \title{{pkgname}: Playing with Braces}
#>        |        ^
#> checkRd: (-3) file2c241344a233:10: Lost braces
#>     10 | Plain-text math: integer in {1, 2, ..., n}, (-1)^{n-1}
#>        |                             ^
#> checkRd: (-3) file2c241344a233:10: Lost braces
#>     10 | Plain-text math: integer in {1, 2, ..., n}, (-1)^{n-1}
#>        |                                                  ^

I think it would be nice if roxygen2 could escape the braces "as necessary" when it generates the Rd code.

[jphill01]

@bastistician I just submitted an update my R package VLF: https://cran.r-project.org/web/checks/check_results_VLF.html. It seems however that I have this very issue with 'lost braces` as in:

Version: 1.1 
Check: Rd files 
Result: NOTE 
  checkRd: (-1) aminoAcidFun.Rd:37: Lost braces
      37 | \item{ownVLFreduced}{ownVLFMatrix}{A matrix containing only those specimen that have VLFs as well as the amino     acids at the positions that contain VLFs and NAs in all other positions of the sequence.  Only appears if own is not NULL.}
         |                                   ^
  checkRd: (-1) vlfFun.Rd:36: Lost braces
      36 | \item{ownVLFreduced}{ownVLFMatrix}{A matrix containing only those specimen that have VLFs as well as the     nucleotides at the positions that contain VLFs and NAs in all other positions of the sequence.  Only appears if own is not NULL.}
         |   

which is a bit different to your example. Any ideas?

[bastistician]

@jphill01 This thread is about a bug in roxygen2's Markdown mode. AFAICS, these Rd files in your package weren't even generated by roxygen2. You'll find a trivial copy-paste lapsus in the item list if you look at the Rd files. If you are still having problems passing R CMD check, you could ask on R-package-devel.

(The maintainer's of this repo may wish to mark these comments as off-topic.)

[hadley]

I agree that it would be nice to automatically escape these braces, but at this time I don't think it's feasible. The markdown syntax is a markdown-Rd hybrid parsed by a Frankenstein of commonmark + regular expressions. Unfortunately I don't see a realistic way to improve the situation that either doesn't lead to playing whack-a-mole with new bugs or rewriting the entire parsing system from first principles.

[bastistician]

Thanks for taking a look. I can understand the conclusion. Checking with R >= 4.4.0 should note these lost braces anyway, so developers are informed and can switch to specific \pkg{} markup etc. or escape the braces as needed.