作者：Yihui Xie
译者：郑宝童
日期：2021.05.14

1.4 Two rendering approaches

Merging all chapters into one Rmd file and knitting it is one way to render the book in bookdown. There is actually another way: you may knit each chapter in a separate R session, and bookdown will merge the Markdown output of all chapters to render the book. We call these two approaches “Merge and Knit” (M-K) and “Knit and Merge” (K-M), respectively. The differences between them may seem subtle, but can be fairly important depending on your use cases.

其中一种在bookdown中渲染书的方法是将所有章节合并到一个Rmd文件中，并knitting它。实际上还有另一种方法:您可以在单独的R session中knit每个章节，而bookdown将合并所有章节的Markdown输出来呈现这本书。我们分别称这两种方法为“Merge and Knit” (M-K) 和“Knit and Merge” (K-M)。它们之间的区别可能看起来很细微，但应该对您的案例蛮重要。

  • The most significant difference is that M-K runs all code chunks in all chapters in the same R session, whereas K-M uses separate R sessions for individual chapters. For M-K, the state of the R session from previous chapters is carried over to later chapters (e.g., objects created in previous chapters are available to later chapters, unless you deliberately deleted them); for K-M, all chapters are isolated from each other.2 If you want each chapter to compile from a clean state, use the K-M approach. It can be very tricky and difficult to restore a running R session to a completely clean state if you use the M-K approach. For example, even if you detach/unload packages loaded in a previous chapter, R will not clean up the S3 methods registered by these packages.
  • 最显著的区别是，M-K在相同的R session中运行所有章节中的所有代码块，而K-M为各个章节使用单独的R会话。对于M-K，前一章的R会话状态会被转移到后面的章节(例如，在前一章创建的对象对后面的章节是可用的，除非你故意删除它们);对于K-M，所有章节都是相互隔离的如果您希望每个章节都能在干净的状态下编译，可以使用K-M方法。如果使用M-K方法，要将正在运行的R session 恢复到完全干净的状态是非常棘手和困难的。例如，即使您分离/卸载在前一章中加载的包，R也不会清理这些包所记录的S3方法。
  • Because knitr does not allow duplicate chunk labels in a source document, you need to make sure there are no duplicate labels in your book chapters when you use the M-K approach, otherwise knitr will signal an error when knitting the merged Rmd file. Note that this means there must not be duplicate labels throughout the whole book. The K-M approach only requires no duplicate labels within any single Rmd file.
  • 因为knitr不允许在源文档中出现重复块标签，所以当您使用M-K方法时，您需要确保在您的书籍章节中没有重复标签，否则在knitr 合并过的Rmd文件时，knitr将报出错误信息。注意，这意味着整本书不能有重复的标签。而K-M方法只要求在任何单个Rmd文件中不存在重复的标签。
  • K-M does not allow Rmd files to be in subdirectories, but M-K does.
  • K-M不允许将Rmd文件放在子目录中，但是M-K允许。

    The default approach in bookdown is M-K. To switch to K-M, you either use the argument new_session = TRUE when calling render_book(), or set new_session: yes in the configuration file _bookdown.yml.

You can configure the book_filename option in _bookdown.yml for the K-M approach, but it should be a Markdown filename, e.g., _main.md, although the filename extension does not really matter, and you can even leave out the extension, e.g., just set book_filename: _main. All other configurations work for both M-K and K-M.

bookdown 的默认方法是M-K。要切换到K-M，你可以在调用 render_book()时使用参数 new_session = TRUE ，或者在配置文件 _bookdown.yml中设置new_session: yes 。你可以在 _bookdown.yml 中为K-M 方法配置 book_filename 选项，但它必须是markdown文件名，例如_main.md。 book_filename 选项的文件名扩展名并不重要，你甚至可以忽略扩展名，例如，只设置book_filename: _main。所有其他配置都适用于M-K和K-M。

  1. Of course, no one can stop you from writing out some files in one chapter, and reading them in another chapter. It is hard to isolate these kinds of side-effects.↩︎