带有多行 LaTeX 方程的 R 帮助页面

Question

我正在使用

roxygen2

编写 R 包文档。我想将以下多行方程插入到帮助页面中，但我的 LaTeX 代码没有被渲染。

#' hello2
#'
#' @description
#' \deqn{
#' F(t)= \begin{cases}\alpha(t) f_{L}(t)+[1-\alpha(t)] f_{C}(t) & t_{L}<t<t_{C} \\ \beta(t) f_{C}(t)+[1-\beta(t)] f_{R}(t) & t_{C}<t<t_{R}\end{cases}
#' }
#' 
#' @export
hello2 <- function() {}

Answer 1

新答案

R 4.2.0 中添加了对 Rd 文件 HTML 渲染中 KaTeX 的支持。 R 4.2.2 中添加了 Rd 文件 PDF 渲染中对 amsmath 的支持。因此，带有

Depends: R (>= 4.3)

的包可以使用

\deqn

安全地指定多线方程。不需要mathjaxr。

---

原答案

只是为了证明，一旦正确集成了 mathjaxr，这是可能的：

tmp <- tempfile()
dir.create(tmp)
cwd <- setwd(tmp)

pkgname <- "foo"
usethis::create_package(pkgname, rstudio = FALSE, open = FALSE,
                        fields = list(Imports = "mathjaxr", RdMacros = "mathjaxr"))
setwd(pkgname)
text <- "#' A title
#' 
#' \\loadmathjax{}
#' A description.
#' 
#' @param a,b Arguments.
#' 
#' @details
#' An irrelevant equation:
#' \\mjtdeqn{F(t) = \\left\\lbrace\\begin{array}{ll} \\alpha(t) f_{L}(t) + \\lbrack 1 - \\alpha(t) \\rbrack f_{C}(t)\\,, & t_{L} < t < t_{C}\\,, \\cr \\beta(t) f_{C}(t) + \\lbrack 1 - \\beta(t) \\rbrack f_{R}(t)\\,, & t_{C} < t < t_{R}\\,. \\end{array}\\right.}{%
#'           F(t) = \\begin{cases} \\alpha(t) f_{L}(t) + \\lbrack 1 - \\alpha(t) \\rbrack f_{C}(t)\\,, & t_{L} < t < t_{C}\\,, \\cr \\beta(t) f_{C}(t) + \\lbrack 1 - \\beta(t) \\rbrack f_{R}(t)\\,, & t_{C} < t < t_{R}\\,. \\end{cases}}{%
#'           ... a plain text translation ...}
#' 
#' @noMd
#' @export
#' @importFrom mathjaxr preview_rd
add <- function(a, b) a + b
"
cat(text, file = file.path("R", "add.R"))
roxygen2::roxygenize(".")

PDF输出

mathjaxr::preview_rd("add.Rd", type = "pdf")

HTML 输出

mathjaxr::preview_rd("add.Rd", type = "html")

纯文本输出

mathjaxr::preview_rd("add.Rd", type = "txt")

几点说明

• 我们只是转义反斜杠，因为我们将

  add.R

  的内容输入到字符串中。

  cat

  创建的文本文件不包含转义符。

• \loadmathjax{}

  将 MathJax 脚本注入 HTML 文件中。它通常放置在描述的顶部，以便您可以在之后的任何地方排版数学。
• 我们使用宏

  \mjtdeqn

  依次为 PDF 手册提供 LaTeX、为 HTML 帮助页面提供 LaTeX、为纯文本帮助页面提供纯文本。在更简单的情况下，您还可以使用其他宏。它们都记录在README中，您应该仔细阅读。
• 在 PDF 领域，您无法访问 AMS 扩展，因此您必须使用

  cases

  自行实现

  array

  。
• 在 PDF 和 HTML 字段中，您需要使用

  \cr

  代替多行环境中常用的

  \\

  。我不知道为什么。
• 我还没有弄清楚如何在纯文本字段中编码换行符（还）。很难将多行方程转换为没有换行符的纯文本......
• 我使用

  @noMd

  禁用了对此标头的 Markdown 支持，因为根据我的经验，Markdown 解析器并不总是能很好地与 mathjaxr 宏配合使用。在我自己的软件包中，我通过

  DESCRIPTION

  全局禁用 Markdown 支持。
• 您需要在包中的某个位置使用

  @importFrom mathjaxr preview_rd

  来规避

  R CMD check

  关于在 Imports 中包含

  mathjaxr

  的警告，而不使用 mathjaxr 导出的任何函数。
• 要在不安装软件包的情况下预览使用 MathJax 的帮助页面，您需要使用

  mathjaxr::preview_rd

  。 devtools 预览将向您显示未渲染的 LaTeX 代码。
• 您必须决定 MathJax 支持是否值得在您的 Imports 中拥有

  mathjaxr

  。任何尝试安装您的软件包的人都必须安装 mathjaxr。

清洁

setwd(cwd)
unlink(tmp, recursive = TRUE)

Answer 2

基于 Mikael 的解决方案，更干净的版本：

#' A title
#'
#' @param a,b Arguments.
#'
#' @section options:
#' - `item1`:
#'    \mjtdeqn{
#'    F(t) = \left\lbrace\begin{array}{ll}
#'         \alpha(t) f_{L}(t) + (1 - \alpha(t)) f_{C}(t), & t_{L} < t < t_{C}, \cr
#'         \beta(t) f_{C}(t) + (1 - \beta(t)) f_{R}(t), & t_{C} < t < t_{R}. \end{array}\right.}{%
#'    F(t) = \begin{cases}
#'         \alpha(t) f_{L}(t) + (1 - \alpha(t)) f_{C}(t), & t_{L} < t < t_{C}, \cr
#'         \beta(t) f_{C}(t) + (1 - \beta(t)) f_{R}(t), & t_{C} < t < t_{R}. \end{cases}}{}
#'
#' - item2
#'
#' \loadmathjax{}
#' @export
#' @importFrom mathjaxr preview_rd
add <- function(a, b) a + b

Markdown

与本示例中的

mathjaxr

兼容

mathjaxr::preview_rd("add.Rd", type = "pdf")
mathjaxr::preview_rd("add.Rd", type = "html")

上面的脚本返回与 Mikael 相同的结果。