无论Rd文件是否包含\PR{}
,R CMD build
的行为都不同。有关宏的详细信息,请参阅编写R扩展。
Rd文件不包含\PR{}
时的示例:
$ R CMD build test
* checking for file 'test/DESCRIPTION' ... OK
* preparing 'test':
* checking DESCRIPTION meta-information ... OK
* installing the package to process help pages
* saving partial Rd database
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building 'test_0.1.tar.gz'
Rd文件包含\PR{}
时的示例:
$ R CMD build test
* checking for file 'test/DESCRIPTION' ... OK
* preparing 'test':
* checking DESCRIPTION meta-information ... OK
* installing the package to process help pages
* saving partial Rd database
* building the PDF package manual # <- this
Hmm ... looks like a package # <- this
Converting Rd files to LaTeX # <- this
Creating pdf output from LaTeX ... # <- this
Saving output to 'xxx/test.pdf' ... # <- this
Done # <- this
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building 'test_0.1.tar.gz'
额外的阶段(即building the PDF package manual
,在旧计算机上可能相当慢...)是由于.build_packages()
中对..Rd2pdf()
的调用。但是我不明白是什么触发了这个阶段。此外,它只对\PR{}
触发,而不对其他宏(如\CRANpkg{}
和\doi{}
)触发。
有人能追溯发生了什么以及为什么吗?问题只针对base R函数。我不使用package:devtools
这样的助手。
最小测试包
Package 结构:
test
test/man
test/man/one.Rd
test/R
test/R/one.R
test/DESCRIPTION
test/NAMESPACE
test/man/one.Rd
:
\name{one}
\alias{one}
\title{Get One}
\description{
Rd file containing or not the PR macro:
\PR{1} % comment/uncomment this line as needed
but containing other macros:
\CRANpkg{ggplot2} and \doi{10.1002/wics.147}
}
\usage{
one()
}
test/R/one.R
:
one <- function() 1
test/DESCRIPTION
:
Package: test
Version: 0.1
Title: Test
Author: Nobody
Maintainer: Nobody <no@body.org>
Description: Test.
License: GPL-3
test/NAMESPACE
:
export(one)
使用以下工具生成、检查和安装:
$ R CMD build test
$ R CMD check test_0.1.tar.gz
$ R CMD INSTALL test_0.1.tar.gz
2条答案
按热度按时间xzlaal3s1#
以下是导致这种差异的机制的解释。
可以在
file.path(R.home(), "share/Rd/macros/system.Rd")
文件中看到系统宏定义。\PR
的定义为你提到的其他定义是
\CRANpkg
宏不执行R代码,因此不会触发软件包安装。\doi
宏在生成时执行代码。就在您链接的代码上方,您会看到以下测试:
manual
变量默认为TRUE
,但命令行选项--no-manual
将其设置为FALSE
。测试的下一部分说明您可以通过DESCRIPTION
文件中的一个字段取消手动。getDynamicFlags()
函数在Rd文件中查找安装或渲染时执行的代码,而不是构建时执行的代码,因此\doi
宏不会触发参考手册的构建。\PR
宏没有指定它运行的阶段,文档中似乎没有提到默认的运行时,但显然getDynamicFlags(Rd)[c("install", "render")]
返回了TRUE
。我猜默认值是呈现时,以防bug数据库的URL在将来的R版本中发生变化。[编辑:文档确实说默认值是"install"
。]因此,要抑制此构建,请将
BuildManual: false
放在DESCRIPTION
文件中或将--no-manual
放在R CMD build
命令行中。yyhrrdl82#
R's Bugzilla上来自R内核的响应:
\PR
宏最初只在R自己的NEWS.Rd中使用,其中stage
并不真正适用。Sexpr的默认值
stage=install
可能有历史原因:我同意stage=build
在非基础包中通常是更好的,以避免PDF手册中的tarball文件爆炸。由于\doi
宏的原因,通常会包含部分Rd db。我还没有检查是否/如何修改PR宏而不中断NEWS.Rd处理。注意,WRE中提到的宏只是作为
\newcommand
的一个例子;我不认为这是通用的。在一个贡献的软件包的帮助中,“PR#”指的是哪个bug跟踪器是不清楚的。在这里简单地包括一个bug报告的普通URL可能会更好。如果你还想使用它,你可以在Rd文件的开头设置
\RdOpts{stage=build}
(由于Bug 18073,这需要R〉= 4.1.0)。