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.

[grantmcdermott]

Just noting that I also got bit by this recently via an @inherit stats::density details tag. (The inherited .Rd contains R 4.4+'s \cite{}\out{<a ...>} markup, which gets wrapped in extra braces in the generated Rd and triggers checkRd: Lost braces.)

Unfortunately, the \pkg{} escape workaround obviously doesn't apply here, since the problematic markup is upstream in base R's own Rd files. I'm guessing other folks will run into a similar issue. In my case, it looks like the simplest solution is to drop the @inherit tag and just write a short @details section pointing to the source instead.

[bastistician]

I think these observations are slightly off-topic. Still, a few comments:

• There is currently no citation in the Details section of ?stats::density. I guess you were inheriting the bw argument description from R 4.6.0 with its \bibcitet{R:Venables+Ripley:2002}, which gets expanded to a build-time Rd \Sexpr that generates an in-text citation that is hyperlinked in HTML help.
• Inheriting documentation from other packages using roxygen "is best used sparingly". One undesirable consequence is that all build/install-stage dynamic help fragments from the source become static as on your build machine. In this particular case, the citation target (the reference section) would also be missing.
• I agree the "lost braces" note might be confusing here but it is correct and helpful in the sense that it pointed out a documentation problem.
• Rather than copying the argument documentation from your current R's ?stats::density, I'd suggest to document bw "locally" using a link, for example: "the smoothing bandwidth to be used, see \code{\link[stats]{density}}".

Hope this helps.

PS: I would not call the \pkg Rd macro a "workaround"; it is the canonical markup for package names.

[grantmcdermott]

Thanks @bastistician, definitely helpful. I'll action on my side. Cheers.