R Bookdown _bookdown.yml

Question

Bookdown 有许多配置选项，我发现很难理解如何知道选项是否存在，以及这些选项背后的逻辑。

具体来说，我发现很难描述 _bookdown.yml 中有哪些种类选项，因为至少还有两个其他地方可以说明选项：

• 在_output.yml，
• 函数调用的参数，例如bookdown::render_book。

在我看来，_bookdown.yml 和 bookdown::render_book 等函数的参数之间没有任何类型的 1 对 1 映射，因此 _bookdown.yml 似乎不仅仅是记录选项的不同方式函数调用。

我们可以在源代码中看到 `_bookdown.yml' 控制了一些config options，但不是全部。

所以 - 换个说法 - 为什么_bookdown.yml 是一个单独的配置文件，它应该包含的内容的定义在哪里/是什么？

举一个有代表性的例子，_bookdown.yml 中有一个chapter_name 选项可以使用。我有以下问题：

1. 我们怎么知道这是一个选项，因为文档here 甚至示例here 中都没有引用它。
2. 一旦我们知道它的存在，我如何知道它有什么作用？所有这些选项是否都会传递给其他包（例如 pandoc、rmarkdown）？我唯一能找到对chapter_name 的引用是在bookdown 的CRAN 源代码中，即使在那里我也无法真正弄清楚它是如何被使用的。

注意，作者_bookdown.yml的讨论是here，但我还是不太明白。

Answer 1

以下是对代码库的一些调查结果：

我们可以看到bookdown::render_book 中的“config”变量是通过load_config 中的load_config 函数从_bookdown.yml here 填充的，该函数可以在utils.R 中找到。

load_config 似乎做了两件事——它将config 的内容存储在一个名为opts 的主选项列表中，其中config 只是一个元素，然后返回那个config 元素。

请注意，opts 最初定义为 here。它是从knitr:::new_defaults 创建的，可以在here 找到。

config 变量随后出现在代码库的多个部分中。

following code代表：

  if (is.na(new_session)) {
    new_session = FALSE
    if (is.logical(config[['new_session']])) new_session = config[['new_session']]
  }

所以我们可以看到，如果new_session作为函数参数直接传递给bookdown::render_book，就被使用了。否则会尝试从_bookdown.yml 文件加载它。

config 在bookdown::render_book 中作为参数传递了很多。例如，我们可以看到它在utils.R 的source_files 函数中使用。

我们得出什么结论？ _bookdown.yml 允许您填充 bookdown 包的全局选项列表。每当您看到 config（这是一个列表）正在使用代码库时，您可以通过填充 _bookdown.yml 来设置此列表的元素

我还没有找到可以在_bookdown.yml 中指定的选项的完整列表，但可以轻松找出可能的选项的一种方法是search for examples on Github。