R Bookdown _bookdown.yml

Question

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

具体来说，我发现很难描述在_bookdown.yml中有什么样的选项，因为至少还有另外两个地方可以声明选项：

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

在我看来，_bookdown.yml和像bookdown::render_book这样的函数的参数之间并没有1到1的映射，所以_bookdown.yml似乎不仅仅是记录函数调用选项的另一种方式。

我们可以从源代码中看到，`_bookdown.yml‘控制着一些配置选项，但不是所有的。

因此，要重新表述这个问题--为什么_bookdown.yml是一个单独的配置文件，以及它应该包含什么内容的定义在哪里？

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

1. 我们如何知道这是一个选项，因为在文档这里中甚至在示例这里中都没有引用它。
2. 一旦我们知道它的存在，我如何发现它有什么影响？所有这些选项是否都被传递到其他包(例如pandoc，rmarkdown)？我唯一能找到chapter_name引用的地方是下单的CRAN源代码，即使在那里，我也不知道它是如何被使用的。

注意，作者对_bookdown.yml的讨论是这里，但我仍然不完全理解。

Answer 1

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

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

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

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

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

以下代码具有代表性：

  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中的utils.R函数中使用。

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

我还没有找到可以在_bookdown.yml中指定的选项的全面列表，但是一种容易找到可能的方法是查找Github上的示例。