Submit PRs for CRAN packages with "Lost braces" NOTE on "Rd files" check

[hturner]

This task has been proposed by R Core developer Kurt Hornik, @kurthornik.

Background

The R package check (R CMD check) includes an "Rd files" check that returns a NOTE if issues are found in the .Rd source files for package documentation.

One part of this check is for "Lost braces", meaning that braces have been incorrectly escaped resulting in incorrectly formatted documentation.

This task is to submit pull requests to CRAN packages that have such a note, where the package is hosted on GitHub or another public repo, prioritising the packages with a higher number of reverse dependencies.

Identifying relevant packages

We can get the check results from the "r-devel-linux-x86_64-debian-gcc" machine, which are regularly updated (https://cran.r-project.org/web/checks/check_details_r-devel-linux-x86_64-debian-gcc.html). They were updated just before I ran this code, which identifies packages with any note about Rd files:

library(tools)

# get check information and identify packages with Rd files NOTE
details <- CRAN_check_details(flavors = "r-devel-linux-x86_64-debian-gcc")
Rd_NOTE <- subset(details, Check == "Rd files" & Status == "NOTE")
dim(Rd_NOTE)
#> [1] 1297    8

we can merge in additional information about the package:

# merge in package info (lose a few that we don't have info for)
pdb <- CRAN_package_db()
Rd_NOTE <- merge(Rd_NOTE, pdb)
dim(Rd_NOTE)
#> [1] 1289   74

Now we can restrict to those hosted on GitHub, GitLab or Bitbucket, and only those packages with the "Lost Braces" NOTE (this could be adapted to pick up other issues, if there is time).

# restrict "Lost braces" and packages that use GitHub to report issues
TODO <- Rd_NOTE[grepl("^http?s://(github.com|gitlab.com|bitbucket.org).*issues", 
                      Rd_NOTE$BugReports),]
TODO <- TODO[grepl("Lost braces", TODO$Output),]
dim(TODO)
#> [1] 402  74

Finally we prioritize by number of reverse dependencies:

# prioritise by n revdeps
revdeps <- strsplit(TODO$`Reverse depends`, ",")
n_revdeps <- lengths(revdeps)
n_revdeps[is.na(revdeps)] <- 0
    
TODO <- cbind(n_revdeps = n_revdeps, TODO)[order(n_revdeps, decreasing = TRUE),]
head(TODO[, c("n_revdeps", "Package", "BugReports")], 15)
#>      n_revdeps       Package                                                   BugReports
#> 399         12   gamlss.dist https://github.com/mstasinopoulos/GAMLSS-Distibutions/issues
#> 532          7         irlba                      https://github.com/bwlewis/irlba/issues
#> 665          6     miscTools          https://github.com/arne-henningsen/miscTools/issues
#> 79           5        BBmisc                 https://github.com/berndbischl/BBmisc/issues
#> 1057         4       shinyjs                   https://github.com/daattali/shinyjs/issues
#> 574          3 LaplacesDemon       https://github.com/LaplacesDemonR/LaplacesDemon/issues
#> 926          3 reactablefmtr              https://github.com/kcuilla/reactablefmtr/issues
#> 1094         3         smoof                  https://github.com/jakobbossek/smoof/issues
#> 1127         3         sqldf                https://github.com/ggrothendieck/sqldf/issues
#> 1170         3         sylly                https://github.com/unDocUMeantIt/sylly/issues
#> 1254         3   viridisLite            https://github.com/sjmgarnier/viridisLite/issues/
#> 118          2         brglm                    https://github.com/ikosmidis/brglm/issues
#> 559          2        koRpus               https://github.com/unDocUMeantIt/koRpus/issues
#> 676          2        mlrMBO                     https://github.com/mlr-org/mlrMBO/issues
#> 171          1          cmna                     https://github.com/k3jph/cmna-pkg/issues

It turns out all the packages with >1 reverse dependency are hosted on GitHub.

Fixing the issues

Sign in to GitHub and clone the repo. Make a new branch e.g. "lost-braces" to make your changes.

View the issues for the package you are working on. You could do this from the check page e.g.
https://www.r-project.org/nosvn/R.check/r-devel-linux-x86_64-debian-gcc/gamlss.dist-00check.html
or from the TODO dataframe:

cat(TODO["399", "Output"])
#> checkRd: (-1) GEOM.Rd:56: Lost braces
#>     56 | for eqn{y=0,1,2,3,...} and \eqn{\mu>0},   see pp 473-474 of Rigby et al. (2019).
#>        |        ^
#> checkRd: (-1) GU.rd:61: Lost braces
#>     61 | \emph{Journal of Statistical Software}, Vol. \bold{23}, Issue 7, Dec 2007, \\doi{10.18637/jss.v023.i07}.
#>        |                                                                                 ^
#> checkRd: (-1) IG.Rd:55: Lost braces
#>     55 | \emph{Journal of Statistical Software}, Vol. \bold{23}, Issue 7, Dec 2007, \\doi{10.18637/jss.v023.i07}.
#>        |                                                                                 ^
#> checkRd: (-1) LOGITNO.Rd:55: Lost braces
#>     55 | \emph{Journal of Statistical Software}, Vol. \bold{23}, Issue 7, Dec 2007, \\doi{10.18637/jss.v023.i07}.
#>        |                                                                                 ^
#> checkRd: (-1) Multinomial.Rd:69: Lost braces
#>     69 | The function \code{MULTIN()} can be used instead of code{MN3()}, \code{MN4()} and \code{MN5()} by specifying the number of levels of the response. Note that \code{MULTIN(2)} will produce a binomial fit. 
#>        |                                                         ^
#> checkRd: (-1) PARETO2.Rd:38: Lost braces
#>     38 | The parameters are  \code{mu} and \code{sigma} in both functions but the parameterasation different.  The \code{mu} is identical for both \code{PARETO2()} and  \code{PARETO2o()}. The \code{sigma} in  \code{PARETO2o()} is the inverse of the \code{sigma} in code{PARETO2()} and coresponse to the usual parameter \code{alpha} of the Patreto distribution. The functions \code{dPARETO2}, \code{pPARETO2}, \code{qPARETO2} and \code{rPARETO2} define the density, distribution function, quantile function and random generation for the \code{PARETO2} parameterization of the Pareto type 2 distribution while the functions \code{dPARETO2o}, \code{pPARETO2o}, \code{qPARETO2o} and \code{rPARETO2o} define the density, distribution function, quantile function and random generation for the original \code{PARETO2o} parameterization of the Pareto type 2 distribution
#>        |                                                                                                                                                                                                                                                                     ^
#> checkRd: (-1) PIG.Rd:31: Lost braces
#>     31 | generation for the Poisson-inverse Gaussian \code{PIG()}, distribution.  Also code{dPIG2}, \code{pPIG2}, \code{qPIG2} and \code{rPIG2} are the equivalent functions for code{PIG2()}
#>        |                                                                                   ^
#> checkRd: (-1) PIG.Rd:31: Lost braces
#>     31 | generation for the Poisson-inverse Gaussian \code{PIG()}, distribution.  Also code{dPIG2}, \code{pPIG2}, \code{qPIG2} and \code{rPIG2} are the equivalent functions for code{PIG2()}
#>        |                                                                                                                                                                             ^
#> checkRd: (-1) SI.Rd:70: Lost braces
#>     70 | \emph{Journal of Statistical Software}, Vol. \bold{23}, Issue 7, Dec 2007, \\doi{10.18637/jss.v023.i07}.
#>        |                                                                                 ^

The problems are indicated with a caret (^). In the first couple of examples:

• for eqn{y=0,1,2,3,...} should be: for \eqn{y=0,1,2,3,...}
• \\doi{10.18637/jss.v023.i07}. should be \doi{10.18637/jss.v023.i07}.

In these examples the author does not intend to include a literal brace character in the rendered help file. If they did, it would need to be escaped, i.e. \{ would be rendered as {. Refer to Writing R Extensions if you are unsure of the correct syntax.

Make corrections in the appropriate file: .R if the packages uses roxygen2, or .Rd otherwise. if the package uses roxygen2, regenerate the documentation, e.g. with roxygen2::roxygenize() or devtools::document(). Check the Rd file with tools::checkRd() and preview with tools::Rd2HTML() or with devtools::load_all() followed by opening/refreshing the help file.

Once you have fixed the issues, open a PR to the original repo.

[MichaelChirico]

lose a few that we don't have info for

Spot-checked, I think those are packages that have recent updates which fix the "lost braces" NOTE, e.g. {Ecdat}, {istacr}, {lfstat}.

Rd_NOTE[grepl("^http?s://(github.com|gitlab.com|bitbucket.org).*issues", Rd_NOTE$BugReports),]

(NB: typo, ? should come after s). I propose this subset instead:

public_repo_regex <- "https?://(www.)?(github.com|gitlab.com|bitbucket.org|.*github[.]io/)"
TODO <- Rd_NOTE |>
  subset(
    (grepl(public_repo_regex, BugReports) | grepl(public_repo_regex, URL))
    & grepl("Lost braces", Output, fixed = TRUE)
  )
nrow(TODO)
# [1] 538

That adds {ez}, {stabs}, and {antitrust} to the top 15 list, and {gamlr}, {ptw} and {binr} before {cmna}.

[MichaelChirico]

Here also are the 15 packages with >1 reverse dependency that don't have any listed repo:

           Package BugReports                                              URL
173        CNLTreg       <NA>                                             <NA>
178       combinat       <NA>                                             <NA>
263            drc       <NA> http://www.r-project.org, http://www.bioassay.dk
414         geiger       <NA>                                             <NA>
503          IHSEP       <NA>                                             <NA>
640         mcmcse       <NA>                                             <NA>
684         mnormt       <NA>     http://azzalini.stat.unipd.it/SW/Pkg-mnormt/
714        mvabund       <NA>                                             <NA>
778   orthopolynom       <NA>                                             <NA>
825        picante       <NA>                                             <NA>
832  plotfunctions       <NA>        https://jacolienvanrij.com/tutorials.html
989         rpanel       <NA>                                             <NA>
1095            sn       <NA>                http://azzalini.stat.unipd.it/SN/
1208       toolbox       <NA>                                             <NA>
1264    wavemulcor       <NA>                                             <NA>

If we're diligent we can often find GitHub repos for those; found these:

https://github.com/nunesmatt/CNLTreg
https://github.com/mwpennell/geiger-v2
https://github.com/dvats/mcmcse
https://github.com/skembel/picante
https://github.com/adrian-bowman/rpanel

I've found that searching for words from the DESCRIPTION is pretty reliable for finding the packages, example search:

https://github.com/search?q=path%3ADESCRIPTION+%22Analysis+of+Evolutionary+Diversification%22+-repo%3Aandystopia%2Fcran_description_files+-org%3Acran+-org%3Abioc&type=code

[tslumley]

Need to make sure that the repo is actually the place where development for that package happens, which might well not be the case if it's not listed at CRAN. I've had people try to send me pull requests for {survey} on a github repo -- and there the r-forge repo *is* listed. -thomas Thomas Lumley Professor of Biostatistics

…

________________________________________ From: Michael Chirico ***@***.***> Sent: Friday, September 5, 2025 4:37 AM To: r-devel/r-dev-day Cc: Subscribed Subject: Re: [r-devel/r-dev-day] Submit PRs for CRAN packages with "Lost braces" NOTE on "Rd files" check (Issue #110) [https://avatars.githubusercontent.com/u/7606389?s=20&v=4]MichaelChirico left a comment (r-devel/r-dev-day#110)<#110 (comment)> Here also are the 15 packages with >1 reverse dependency that don't have any listed repo: Package BugReports URL 173 CNLTreg <NA> <NA> 178 combinat <NA> <NA> 263 drc <NA> http://www.r-project.org, http://www.bioassay.dk 414 geiger <NA> <NA> 503 IHSEP <NA> <NA> 640 mcmcse <NA> <NA> 684 mnormt <NA> http://azzalini.stat.unipd.it/SW/Pkg-mnormt/ 714 mvabund <NA> <NA> 778 orthopolynom <NA> <NA> 825 picante <NA> <NA> 832 plotfunctions <NA> https://jacolienvanrij.com/tutorials.html 989 rpanel <NA> <NA> 1095 sn <NA> http://azzalini.stat.unipd.it/SN/ 1208 toolbox <NA> <NA> 1264 wavemulcor <NA> <NA> If we're diligent we can often find GitHub repos for those, e.g checking the first 4. https://github.com/nunesmatt/CNLTreg https://github.com/mwpennell/geiger-v2 — Reply to this email directly, view it on GitHub<#110 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AB757PJ7R2EKMGS63TMBHML3RBTGJAVCNFSM6AAAAACFUHLMJKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTENJUGU2TAOJZGA>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[hturner]

@MichaelChirico for packages where there is, in fact, a public repo used for bug reports, we could also add this to the BugReports field of the DESCRIPTION.

[eddelbuettel]

Maybe completing DESCRIPTION files to add a repo address where it exists but is not listed could be a separate task?

[MichaelChirico]

@MichaelChirico for packages where there is, in fact, a public repo used for bug reports, we could also add this to the BugReports field of the DESCRIPTION.

To clarify, do you just have in mind the 6 packages above, or do you also have in mind adding BugReports: as a field for packages with URL a GitHub repo where we can trivially fill in BugReports: ${GITHUB_REPO}/issues?

If the former, I already filed PRs :)

If the latter, maybe that's something R and/or CRAN itself should do instead? That approach is much more scalable / doesn't require 100s of PRs to be reviewed, merged, packages resubmitted.

[bastistician]

Some additional context: The "lost braces" check was added in R 4.4.0, when >3000 CRAN packages were affected. tools::checkRd() tries hard to only raise the warning level for consideration by R CMD check when the braces are markup errors that lead to bad rendering. As summarized in the R Journal "News and Notes" report at the time, the most frequent problems seen were:

• code{...}: missing backslash in front of the macro name
• {1, 2}: in-text set notation, where the braces need escaping or the whole expression needs to be put inside a math \eqn{}
• \itemize{ ... \item{label}{description} ... }: Rd code meant as a description list with initial labels; this needs \describe instead of \itemize, otherwise the element becomes "labeldescription" because an \itemize \item does not take any arguments.

[villegar]

R Dev Day summary

• ADPclust-v0.7: PR opened: Fix issue lost braces ethanyxu/ADPclust#1
• AEenrich-v1.1.0: PR opened: Fix issue lost braces umich-biostatistics/AEenrich#5
• AdhereR-v0.8.1: PR opened: Fix issue lost braces ddediu/AdhereR#204
• BBmisc-v1.13: PR opened: Fix issue lost braces berndbischl/BBmisc#97
• LaplacesDemon-v16.1.6: PR opened: fix notes on CRAN LaplacesDemonR/LaplacesDemon#48
• abclass-v0.4.0: PR opened: Fix issue lost braces wenjie2wang/abclass#1
• academictwitteR-v0.3.1: The repository was archived
• adaptMT-v1.0.0: PR opened: Fix issue lost braces lihualei71/adaptMT#4
• airnow-v0.1.0: PR opened: Fix issue lost braces briandconnelly/airnow#6
• allMT-v0.1.0: PR opened: Fix issue lost braces tmungle/allMT#4
• amapGeocode-v0.6.0: PR opened: Fix issue lost braces womeimingzi11/amapGeocode#5
• brglm-v0.7.2: PR opened: Fix issue lost braces ikosmidis/brglm#1
• cmna-v1.0.5: PR opened: Fix notes for lost braces check on CRAN k3jph/cmna-pkg#1
• downscale-v5.0.0: PR opened: Fix notes for lost braces check on CRAN charliem2003/downscale#3
• ez-v4.4-0: PR opened: Fix notes for lost braces check on CRAN mike-lawrence/ez#74
• gamlss.dist-v6.1-1: PR opened: gamlss-dev/gamlss.dist@31bec78)
• irlba-v2.3.5.1: PR opened: Update documentation to address CRAN note on lost braces bwlewis/irlba#77
• miscTools-v0.6-28: PR opened: Update documentation to address CRAN note on lost braces arne-henningsen/miscTools#1
• mlrMBO-v1.1.5.1: PR opened: Fix CRAN issue "lost braces" mlr-org/mlrMBO#524
• mlxR-v4.2.0: PR opened: Update documentation to address CRAN note on lost braces MarcLavielle/mlxR#37
• shinyjs-v2.1.0: issue fixed by maintainer
• sqldf-v0.4-11: PR opened: Updated sqldf.Rd ggrothendieck/sqldf#58
• sylly-v0.1-6: PR opened: Fix issue lost braces unDocUMeantIt/sylly#1

[MichaelChirico]

@villegar great work! It would also help if you could share any tips you learned in the process about how to scale up this process to possibly make it easier to fix this issue for the remaining 100s of affected packages.

[kurthornik]

>>>> Michael Chirico writes: # MichaelChirico left a comment (r-devel/r-dev-day#110) @villegar great work!

Thanks also from my end!

…

It would also help if you could share any tips you learned in the process about how to scale up this process to possibly make it easier to fix this issue for the remaining 100s of affected packages. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.*Message ID: <r-devel/ ***@***.***>