R Bookdown _bookdown.yml [英] R Bookdown _bookdown.yml

问题描述

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

Bookdown has many configuration options and I am finding it hard to understand how to know whether an option exists, and the logic behind where these options are stated.

特别是我发现很难描述_bookdown.yml中的种类选项，因为至少还有两个其他地方可以说明选项:

Specifically I am finding it hard to describe what kind of options go in _bookdown.yml given that there are at least two other places for stating options:

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

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

It doesn't appear to me that there's any sort of 1 to 1 mapping between _bookdown.yml and arguments to functions like bookdown::render_book, so _bookdown.ymldoesn't seem to be just a different way of recording options to function calls.

我们可以在源代码中看到`_bookdown.yml'正在控制一些配置选项，但不是全部.

We can see in the source code that `_bookdown.yml' is controlling some of the config options but not all of them.

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

So - to rephrase the question - why is _bookdown.yml a separate config file and where/what is the definition of what it should contain?

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

To take a representative example, there is a chapter_name option that can be used in _bookdown.yml. I have the following questions:

1. 我们怎么知道这是一个选项，因为文档中没有引用它此处 甚至在示例中此处.
2. 一旦我们知道它存在，我如何知道它有什么影响?所有这些选项是否都会传递给其他包(例如 pandoc、rmarkdown)?我可以找到对 chapter_name 的引用的唯一地方是 bookdown，即使在那里我也无法弄清楚它是如何被使用的.

1. How are we supposed to know that this is an option, given that it is not referenced in the documentation here or even in the example here.
2. Once we know it exists, how do I found out what effect it has? Do all of these options get passed to other packages (e.g. pandoc, rmarkdown)? The only place I can find reference to chapter_name is in the CRAN source code for bookdown, and even there I can't really figure out how it's being used.

注意，作者对_bookdown.yml的讨论在这里，但我还是不完全明白.

Note, the discussion of _bookdown.yml by the author is here, but I still don't fully understand.

推荐答案

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

Here are some results of investigations into the codebase:

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

We can see that the 'config' variable in bookdown::render_book is populated from _bookdown.yml here, via a function called load_config which can be found in utils.R.

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

load_config seems to do two things - it stores the contents of config within a master options list called opts, of which config is just one element, and then returns that config element.

请注意，opts 最初定义为 这里.它是从 knitr:::new_defaults 创建的，可以在 这里.

Note that opts is initially defined here. It is created from a knitr:::new_defaults which can be found here.

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

The config variable then appears in multiple parts of the codebase.

以下代码具有代表性:>

The following code is representative:

  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 文件加载它.

So we can see that if new_session is passed directly to bookdown::render_book as a function argument, it is used. Otherwise an attempt is made to load it from the _bookdown.yml file.

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

The config is passed around a lot as an argument within bookdown::render_book. So for instance, we can see it being used in the source_files function in utils.R.

我们得出什么结论?_bookdown.yml 允许您填充 bookdown 包的全局选项列表.每当您看到 config(这是一个列表)正在使用代码库时，您都可以通过填充 _bookdown.yml

What do we conclude? _bookdown.yml allows you to populate a list of global options of the bookdown package. Whenever you see config (which is a list) being using the the codebase, you can set elements of this list by populating _bookdown.yml

我还没有找到可以在 _bookdown.yml 中指定的选项的完整列表，但一种轻松找出可能的方法是 在 Github 上搜索示例.

I have not managed to find a comprehensive list of the options that can be specified in _bookdown.yml but one way of easily finding out what is possible is to search for examples on Github.

这篇关于R Bookdown _bookdown.yml的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！