使用 roxygen2 引用文章答案

【问题标题】：Citing articles using roxygen2使用 roxygen2 引用文章
【发布时间】：2015-01-28 11:16:48
【问题描述】：

与this question 一样，我想在函数文档中包含对文章的引用。我对所有文档都使用roxygen2，似乎有一个pull request 到roxygen2 具有必要的功能，但Hadley 拒绝了它，因为roxygen2 处于维护模式。从那以后情况发生了变化吗？还有其他方法可以引用/包含以 BibTeX 格式存储的文章引用吗？

【问题讨论】：

尝试在你的包的inst文件夹下放一个“CITATION”文件？例如，github.com/cran/GMD/blob/master/inst/CITATION
@xb 不是，那个是引用包，不是引用外部文章。
如果您使用这种类型的小插图，请尝试在您的 .Rnw 中包含一个 .bib 文件？例如，\bibliographystyle{plain} \bibliography{vignette.bib}
@xb 谢谢，但同样，这是一个不同的用例。在我编写内联roxygen2 函数文档时，我希望能够使用拉取请求中建议的@cite 标签来引用文章。我知道RMarkdown 允许外部参考书目。

标签： r

【解决方案1】：

Rdpack package 承诺提供您要求的功能。

要进行设置，您还需要将行 RdMacros: Rdpack 添加到包的 DESCRIPTION 文件（注意大写 M），并将 Rdpack 添加到 Imports: 字段。

然后您可以将您的 bibtex 库保存到 inst/REFERENCES.bib，并在您的文档中引用它们：

#' @references{
#'   \insertRef{bibtexKey}{YourPackageName}
#' }
#'
#' # The below line ought to be included in at least one of your documentation
#' # sections, so that roxygen2 adds Rdpack to your NAMESPACE file.
#'
#' @importFrom Rdpack reprompt

我最初在第一次使用该包时遇到了一些错误；重新启动 R 似乎可以解决问题。

如果使用devtools::document() 构建文档，将会遇到关于unknown macro '\insertRef' 的警告，因为devtools 不会读取DESCRIPTION 文件的“RdMacros”行；它们可以被安全地忽略。 devtools 可能无法正确呈现引用，但会在最终构建包时呈现；要在此期间以正确的格式查看它们，您可以从单独的命令窗口运行 R CMD Rd2pdf。

【讨论】：

【解决方案2】：

ms609 总结得很好。我要补充一点，2018 年发布的Rdpack 还提供了用于引用的宏以及使用单个命令insertAllCited{} 生成参考书目的能力。 Vignette Inserting_bibtex_references，也由 ms609 链接，提供最新信息。

Rdpack::viewRd() 可用于在不构建包的情况下查看呈现的引用，例如：

Rdpack::viewRd("./man/filename.Rd")  # text
Rdpack::viewRd("./man/filename.Rd", type = "html") # html

这对于roxygen2 用户可能特别有用，因为roxygen2 处理Rd 文件但不呈现引用。只是不要忘记在调用Rdpack::viewRd() 之前使用devtools::document() 或其他合适的命令更新文档。

【讨论】：

请注意，在 \insertAllCited{} 之前不能放置四个或更多空格！
确实如此，但前提是您为 roxygen2 cmets 激活了降价。请注意，上面@mc609 的示例可以安全使用，只有在您激活markdown 并将\insertRef 与@references 的第二个e 对齐时才会出现问题。