Обработка файлов примеров с помощью roxygen2: обратные слэши дублируются (\ dontrun становится\\dontrun)

Актуальный вопрос

Как я могу избежать того, что \dontrun{ в отдельном файле, содержащий примеры, становится \\dontrun{ в соответствующем Rd файле после roxygenizing?

Я нашел обходное решение, но чувствую, что, возможно, я просто пропустил что-то очевидное, т.е. некоторые настройки roxigenize().

Подробнее

Я думаю, что я заметил возможную ошибку или IMHO, по крайней мере, нежелательное поведение при обработке примеров с roxygen2, которые хранятся в отдельном файле (в отличие от того, чтобы указывать его прямо в реальном коде кислорода).

Проблема заключается в том, что строка \dontrun{ в соответствующих файлах примеров становится \\dontrun{ в результирующем Rd файле после roxygenizing.

Ниже вы найдете иллюстрацию поведения наряду с простым обходным решением

1) Убедитесь, что каталоги

dir.create("src", recursive=TRUE, showWarnings=FALSE)
dir.create("package", recursive=TRUE, showWarnings=FALSE)

# Ensure empty package directory
subdirs <- list.files("package", full.names=TRUE)
if (length(subdirs)) {
    sapply(subdirs, unlink, recursive=TRUE)
}

2) Создайте примерные функции с двумя разными способами вложения примеров

foo1 <- function(x) {message("I'm foo #1"); return(TRUE)}
roxy.1 <- c(
    "#' Title foo1()",
    "#'", 
    "#' Description foo1().",
    "##' This line is commented out",
    "#'", 
    "#' @param x Some R object that doesn't matter.",
    "#' @return \\code{TRUE}.",
    "#' @references \\url{http://www.something.com/}",
    "#' @author John Doe \\email{[email protected]@something.com}",
    "#' @seealso \\code{\\link{foo2}}",
    "#' @example inst/examples/foo1.R"
)
ex.1 <- c(
    "\\dontrun{",
    "foo1()",
    "}"
)

foo2 <- function(y) {message("I'm foo #2"); return(FALSE)}
roxy.2 <- c(
    "#' Title foo2()",
    "#'", 
    "#' Description foo2().",
    "##' This line is commented out",
    "#'", 
    "#' @param y Some R object that doesn't matter.",
    "#' @return \\code{FALSE}.",
    "#' @references \\url{http://www.something.com/}",
    "#' @author John Doe \\email{[email protected]@something.com}",
    "#' @seealso \\code{\\link{foo1}}",
    "#' @examples", 
    "#' \\dontrun{",
    "#' foo2()}",
    "#' }"
)

write(roxy.1, file="src/foo1.R")
write(c("foo1 <-", deparse(foo1)), file="src/foo1.R", append=TRUE)
write(roxy.2, file="src/foo2.R")
write(c("foo2 <-", deparse(foo2)), file="src/foo2.R", append=TRUE)

3) Создание скелета пакета

package.skeleton(name="test", path="package", 
    code_files=c("src/foo1.R", "src/foo2.R"))

4) Создайте отдельный файл примера для foo1()

dir.create("package/test/inst/examples", recursive=TRUE, showWarnings=FALSE)
write(ex.1, file="package/test/inst/examples/foo1.R")

5) Roxygenize

require("roxygen2")
roxygenize(
    package.dir="package/test",
    overwrite=TRUE, 
    unlink.target=FALSE,
    roclets = c("collate", "namespace", "rd")
)

6) Проверить пакет

shell("R CMD check package/test", intern=FALSE)

Усеченный вывод R CMD-проверки, который показывает, что существует проблема с \dontrun{ в ./package/test/man/foo1.Rd

[...]
Warning: parse error in file 'test-Ex.R':
1: unexpected input
19: 
20: \
    ^
* checking examples ... ERROR
Running examples in 'test-Ex.R' failed
The error most likely occurred in:

> ### Name: foo1
> ### Title: Title foo1()
> ### Aliases: foo1
> 
> ### ** Examples
> 
> \dontrun{
Error: unexpected input in "\"
Execution halted
Warning message:
In shell(expr, intern = FALSE) :
  'R CMD check package/test' execution failed with error code 1
>

7) Временное решение

patchRdFiles <- function( 
    path="package",
    name,
    ...
) {
    path <- file.path(path, name, "man")
    if (!file.exists(path)) {
        stop(paste("Invalid directory path: '", path, "'", sep=""))
    }
    files <- list.files(path, full.names=TRUE)  
#ii=files[1]    
    .dead <- sapply(files, function(ii) {
        cnt <- readLines(ii, warn=FALSE)
        if (length(grep("\\\\\\\\dontrun", cnt, perl=TRUE))) {
            message(paste("Correcting: '", ii, "'", sep=""))
            write(gsub("\\\\dontrun", "\\dontrun", cnt), file=ii)
        }
        return(NULL)
    })
    return(TRUE)
}

Это приведет к удалению всех дублированных обратных косых черт в файлах Rd:

patchRdFiles(name="test")

8) Проверка пакета снова

# CHECK PACKAGE AGAIN
path <- "package/test"
expr <- paste("R CMD check", path)
shell(expr, intern=FALSE)

Снова усеченный вывод R CMD. Теперь файл Rd прошел проверку. Текущая ошибка вызвана неполной ./package/test/man/test-package.Rd, которая в данный момент прекрасна

[...]
Warning: parse error in file 'test-Ex.R':
11: unexpected symbol
56: 
57: ~~ simple examples
              ^
* checking examples ... ERROR
Running examples in 'test-Ex.R' failed
The error most likely occurred in:

> ### Name: test-package
> ### Title: What the package does (short line) ~~ package title ~~
> ### Aliases: test-package test
> ### Keywords: package
> 
> ### ** Examples
> 
> ~~ simple examples of the most important functions ~~
Error: unexpected symbol in "~~ simple examples"
Execution halted
Warning message:
In shell(expr, intern = FALSE) :
  'R CMD check package/test' execution failed with error code 1
>

Ответы

Ответ 1

Это ошибка, которая исправлена ​​в последних версиях roxygen2.