r - 获取 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和 here ，后者由 knitr 的开发者 Yihui Xie 提供在其他包中。

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

编辑:我已经接近破解坚果了(似乎)。

查看 parser manual 的表 1-3 (第 5-7 页)，我们可以看到发送到 usage 的文本以“类似 R”的方式解释，而对于 alias被解释为“逐字逐句”。我不确定这到底是什么意思(尽管第 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 中添加了以下内容文件(在主函数定义旁边，以便让所有 1 人都看过我的源代码):

"%\\%" <- 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的眼睛，我的包裹现在完全没有警告 B-)