让 R CMD 检查以了解反斜杠

Question

我正在编写一个我一直使用的函数包，其中一个基本上是 setdiff:

的简短包装

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

所以1:6 %\% 4:6 == 1:3.

记录这似乎是一场斗争。以下是我的 my_package-infix.Rd 文件中出现问题的相关部分：

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

当我运行 R CMD check my_package_0.1.0.tar.gz 我收到警告：

* 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>%’

暗示这可能意味着我需要更多逃避，我尝试调整这些行：

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

但是产生的令人沮丧的警告是：

* 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':
  ‘%\%’

所以现在我们已经从一个未转义的反斜杠变成了两个反斜杠。有些东西不加起来......什么给了？ .Rd parsing manual (2.2.1) 的相关部分没有提供太多帮助：

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.

而且它似乎编译得很好 -- R CMD build 和 R CMD INSTALL 没有错误，当我 library(my_package) 时，我可以运行 ?"%\%" 调出正确的手册页，在那里我得到 A %\% B 的使用情况，正如预期的那样（当我只在 alias 和 usage 中使用一个转义符时）。

我看到其他一些人为此苦苦挣扎但没有解决方案，例如here and here，后者由 knitr 等软件包的开发者 Yihui Xie 开发。

(PS 它甚至没有 build 中间有偶数个反斜杠，因为这意味着百分号没有转义并且 % 被解释为注释.Rd 个文件中的字符）

编辑：我离破解难题又近了一点（看起来）。

查看 parser manual（第 5-7 页）的表 1-3，我们可以看到发送到 usage 的文本以 "R-like" 方式解释，而发送到alias 被解释为 "verbatim"。我不确定这到底是什么意思（尽管第 8-9 页上有描述），但如果我使用 R CMD check，我会得到更少的刻薄：

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

现在只有一个警告：

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

Answer 1

终于想出了一个解决方法。基本上是一堆废话——我仍然认为这是一个错误。但是这里是：

在你的包中添加一堆无用的代码。因为我收到这些警告：

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.

我将以下内容添加到我的 .R 文件中（在主要函数定义旁边，以便所有将阅读我的源代码的人都清楚）：

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

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

并将其添加到我的 .Rd 文件中：

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

（并保持 usage{ A \%\\% B } 不变）。

也就是说，给R CMD check它所要求的，即使它只是浪费文字。

羊毛足以遮住 R CMD check 的眼睛，我的包裹现在完全没有 WARNING-free B-)

让 R CMD 检查以了解反斜杠

Getting R CMD check to understand backslashes

r

package-development