Getting R CMD to check backslash

Question

I am writing a package of functions that I use all the time, one of which is basically a short shell 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 that cause problems:

 \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 a hint that maybe this means that I need more escapage, I tried to tweak these lines:

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

But a frustrating warning:

 * 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 are moving from a raw backslash to two backslashes. Something does not add up ... what gives? The corresponding part of the .Rd parsing (2.2.1) does not provide much support:

The backslash \ is used as an escape character: \\, \%, \ {and \} remove the special value of the second character. The parser will discard the initial backslash and return another character as part of the text. A backslash is also used as the starting character for markup. In an R-like or LaTeX-like context, a backslash and then an alphabetic character fires a macro; the macro name extends to the first non-alphanumeric character. If the name is not recognized by the parser, discards all digits from the end and tries again. If it is not yet recognized, it returns as an UNKNOWN marker. All other uses of backslashes are permitted and passed as a text through the parser.

And it seems that it compiled just fine - R CMD build and R CMD INSTALL give no errors, and when I library(my_package) , can I run ?"%\\%" to bring up the correct manual page, where I get A %\% B when used, as expected (when I use only one output in alias and usage ).

I have seen some other people struggle with this, but there are no solutions, for example. here and here , the last one is Yihui Xie, a knitr developer among other packages.

(PS it’s not even build with an even number of backslashes in the middle, as this means that the percent sign is not escaped, and % interpreted as a comment symbol in .Rd files)

---

EDITOR: I got a little closer to cracking a nut (it seems).

Having looked at tables 1-3 from the parser's manual (pages 5-7), we can see that the text sent to usage is interpreted in the "R-like" style, while for alias interpreted "literally". I'm not sure what this means (despite the descriptions on pages 8-9), but I get less vitriol from the R CMD check if I use:

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

Only one warning:

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

Answer 1

Finally a workaround for this was found out. In fact, these are nonsense - I still claim that this is a mistake. But here goes:

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

• checking code / documentation inconsistencies ... WARNING Functions or methods using 'funchir-infix' in the documentation object, but not in the code: %<unescaped bksl\>%

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

In functions with \ use elements, there must be a corresponding \ alias entry and all their arguments. Records \ usage should correspond to syntactically valid R-code. See the chapter "Writing R documentation files in the manual" Writing R-Extensions ".

I added the following to my .R file (next to the main function definition for clarity for all 1 people who 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 saved usage{ A \%\\\% B } as is).

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

The wool is taut enough over the eyes R CMD check , my packaging is now completely FREE B -)