如何让 roxygen2 将反引号解释为代码格式？

Question

编写带有格式的文档的标准方法code是使用\\code{}.

\n

也就是说，#\' @param foo value passed on to \\code{bar()}变成

\n

\n

论据

\n

foo\xc2\xa0\xc2\xa0\xc2\xa0\xc2\xa0值传递给bar()

\n

\n

但是，我见过一些包（即dplyr）使用反引号而不是\\code{}达到相同的效果。这要好得多，因为它不那么笨重，并且允许非常好的语法突出显示。

\n

但是，如果我在自己的包上尝试这样做，反引号会被解释为...只是反引号，就像任何其他字符一样。

\n

dplyr::across()例如，的文档以以下内容开头：

\n

#\' @description\n#\' `across()` makes it easy to apply the same transformation to multiple [...]\n

\n

它被编译并在手册页中显示为：

\n

\n

描述

\n

across()可以轻松地将相同的转换应用于多个[...]

\n

\n

但如果我在我的包裹上尝试类似的东西，我会得到：

\n

\n

描述

\n

`across()` 可以轻松地将相同的转换应用于多个 [...]

\n

\n

奇怪的是，我已经glue为一个简单的 PR 分叉了该包（它还设法使用反引号进行代码格式化），如果我在本地构建该包，则反引号起作用（我得到code格式化）。我一生都无法弄清楚为什么它在那里起作用但对我的包裹不起作用。

\n

---

\n

那么，我需要修改一些设置才能使其正常工作吗？我检查了dplyr.Rproj但没有发现任何相关内容。我也看了一眼Doxyfile，但不知道它做了什么，也不知道我要在那里寻找什么。

\n

Answer 1

所有功劳都归功于@rawr对这个问题的评论，只是用答案将其形式化：

秘密就在roxygen2 文档中：只需将以下内容添加到包文件的末尾DESCRIPTION：

# DESCRIPTION file
# [... rest of file ...]
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2  # actually works since 6.0.0

正如该代码所暗示的那样，这将 roxygen2 设置为将命令解释为良好的 ol' Markdown，就像我们习惯在 SO 和其他地方使用的那样。这也意味着所有其他标准 Markdown 命令，例如**bold**和*italics*，以及[text](http://www.url.com)由 定义的代码块```、逐项列表和枚举列表等。这是全面的巨大改进。

不过要小心并查看文档，因为有一些问题。例如，开始列表不需要空行，因此不要以#' 1. [...]或开始任何行#' * [...]，否则您会意外创建一个列表！）。还有一些东西还不起作用，但它们都很小。