Получение 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 Руководство по синтаксическому анализу (2.2.1) не предлагает большой помощи:

Обратная косая черта \ используется в качестве escape-символа: \\, \%, \{и \} удаляют специальное значение второго символа. Синтаксический анализатор отбросит начальную обратную косую черту и вернет другой символ как часть текста. Обратная косая черта также используется в качестве начального символа для макросов разметки. В R-подобном или LaTeX-подобном контексте обратный слеш, за которым следует алфавитный символ, запускает макрос; имя макроса продолжается до первого не алфавитно-цифрового символа. Если имя не распознано, парсер сбрасывает все цифры с конца и пытается снова. Если он все еще не распознан, он возвращается как НЕИЗВЕСТНЫЙ токен. Все другие виды использования обратной косой черты разрешены и передаются парсером в виде текста.

И, похоже, скомпилировано очень хорошо - R CMD build а также R CMD INSTALL не дают ошибок, и когда я library(my_package), Я могу бежать ?"%\\%" вытащить соответствующую страницу руководства, где я получаю A %\% B при использовании, как и ожидалось (когда я использую только один escape в alias а также usage).

Я видел, как некоторые другие люди боролись с этим, но без решений, например, здесь и здесь, этот последний от Yihui Xie, разработчика knitr среди других пакетов.

(PS это даже не build с четным числом обратных косых черт в середине, так как это означает, что знак процента не экранирован и % интерпретируется как комментирующий символ в .Rd файлы)

---

РЕДАКТИРОВАТЬ: я стал немного ближе к взломать орех (кажется).

Изучив таблицы 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

Наконец-то нашли способ обойти это. В основном куча глупостей - я до сих пор утверждаю, что это ошибка. Но здесь идет:

Добавьте кучу бесполезного кода в ваш пакет. Так как я получал эти предупреждения:

• проверка на несоответствие кода / документации... ПРЕДУПРЕЖДЕНИЕ Функции или методы с использованием в объекте документации 'funchir-infix', но не в коде: %<unescaped bksl\>%

• проверка Rd \ использовании разделов... ПРЕДУПРЕЖДЕНИЕ Объекты в \ использовании без \ псевдонима в объекте документации 'funchir-infix': %<unescaped bksl>%

Функции с записями \using должны иметь соответствующие записи \alias и документировать все их аргументы. Записи \use должны соответствовать синтаксически действительному R-коду. См. Главу "Написание файлов документации R" в руководстве "Написание R-расширений".

Я добавил следующее к моему .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глаза, моя посылка теперь полностью ПРЕДУПРЕЖДАЮЩАЯ Б-)