Getting R CMD check to understand backslashes

Question

I'm writing a package of functions I use all the time, one of which is basically a short wrapper for setdiff:

"%\\%" <- function(A, B) setdiff(A, B)

so 1:6 %\% 4:6 == 1:3.

Documenting this seems to be a struggle. Here are the relevant parts of my my_package-infix.Rd file which are throwing up issues:

\alias{\%\\\%}
\usage{A \%\\\% B}

When I run R CMD check my_package_0.1.0.tar.gz I get warnings:

* checking for code/documentation mismatches ... WARNING
  Functions or methods with usage in documentation object
  'my_package-infix' but not in code: 
  %<unescaped bksl>%

* checking Rd \usage sections ... WARNING
  Objects in \usage without \alias in documentation object
  'my_package-infix': 
  ‘%<unescaped bksl>%’

Taking the hint that perhaps this means I need more escapage, I tried to adjust those lines:

\alias{\%\\\\\%}
\usage{A \%\\\\\% B}

But the frustrating warning that's produced is:

* checking for code/documentation mismatches ... WARNING    
  Functions or methods with usage in documentation object
  'my_package-infix' but not in code:
  %\\%

* checking Rd \usage sections ... WARNING
  Objects in \usage without \alias in documentation object
  'my_package-infix':
  ‘%\\%’

So now we've gone from an unescaped backslash to two backslashes. Something doesn't add up... what gives? The relevant part of the .Rd parsing manual (2.2.1) doesn't offer much help:

The backslash \ is used as an escape character: \\, \%, \{ and \} remove the special meaning of the second character. The parser will drop the initial backslash, and return the other character as part of the text. The backslash is also used as an initial character for markup macros. In an R-like or LaTeX-like context, a backslash followed by an alphabetic character starts a macro; the macro name continues until the first non-alphanumeric character. If the name is not recognized the parser drops all digits from the end, and tries again. If it is still not recognized it is returned as an UNKNOWN token. All other uses of backslashes are allowed, and are passed through by the parser as text.

And it seems to have compiled just fine -- R CMD build and R CMD INSTALL give no errors, and when I library(my_package), I can run ?"%\\%" to pull up the proper manual page, where I get A %\% B under usage, as expected (when I only use a single escape in alias and usage).

I've seen some other people struggling with this but no solutions, e.g. here and here, this latter by Yihui Xie, developer of knitr among other packages.

(PS it doesn't even build with an even number of backslashes in the middle since this means the percentage sign is not escaped and % is interpreted as a commenting character in .Rd files)

---

EDIT: I've gotten a little bit closer to cracking the nut (it seems).

Looking at Tables 1-3 of the parser manual (pages 5-7), we can see that text sent to usage is interpreted in an "R-like" fashion while that to alias is interpreted "verbatim". I'm not sure exactly what this means (despite the descriptions on pages 8-9), but I get less vitriol from R CMD check if I use:

\alias{\%\\\%}
\usage{A \%\\% B}

Only one warning now:

* checking Rd \usage sections ... WARNING
  Bad \usage lines found in documentation object 'funchir-infix':
  A %<unescaped bksl>

Answer 1

Finally figured out a workaround to this. Basically a bunch of nonsense -- I still contend this is a bug. But here goes:

Add a bunch of useless code to your package. Since I was getting these warnings:

• checking for code/documentation mismatches ... WARNING Functions or methods with usage in documentation object 'funchir-infix' but not in code: %<unescaped bksl\>%

• checking Rd \usage sections ... WARNING Objects in \usage without \alias in documentation object 'funchir-infix': %<unescaped bksl>%

Functions with \usage entries need to have the appropriate \alias entries, and all their arguments documented. The \usage entries must correspond to syntactically valid R code. See chapter ‘Writing R documentation files’ in the ‘Writing R Extensions’ manual.

I added the following to my .R file (next to the main function definition for clarity to all 1 people that will ever go through my source code):

"%\\%" <- function(A, B) setdiff(A, B)

"%<unescaped bksl>%" <- function(){
  cat("What are you thinking? Don't use this function. See ?\"%\\%\"")
}

And add this to my .Rd file:

\alias{\%<unescaped bksl>\%}

(And kept usage{ A \%\\\% B } as is).

That is, give R CMD check what it's asking for, even if it's just a waste of text.

The wool sufficiently pulled over R CMD check's eyes, my package is now fully WARNING-free B-)