R溝通｜Bookdown中文書稿寫作手冊（中）

本教程來自華東師范大學湯銀才教授，本人已授權。為了獲得更好的閱讀體驗，可在文末直達原文網(wǎng)站。

第 2 章 bookdown速覽

這是第 2 章的內(nèi)容，概要性地講解基于bookdown拓展包進行圖書排版的整體思路與實現(xiàn)方式.

2.1 關于bookdown

bookdown擴展包 (https://github.com/rstudio/bookdown) 是繼knitr和rmarkdown擴展包之后， 另一個增強markdown格式的擴展， 使得Rmd格式可以支持公式、定理、圖表、文獻自動編號和引用等適用于編寫書籍的功能。在bookdown的管理下一本書的內(nèi)容可以按章節(jié)分解成多個Rmd文件， 其中可以包含可執(zhí)行的R代碼， R代碼生成的統(tǒng)計匯總結(jié)果、表格、圖形可以自動插入到生成的內(nèi)容中， 表格和圖形可以是浮動排版的。書的輸出格式包括支持gitbook格式的網(wǎng)頁圖書， 也可以經(jīng) LATEX 編譯器轉(zhuǎn)換的PDF圖書，還可以生成ePub等格式的電子書。建議使用RStudio集成環(huán)境來編輯、管理和生成這樣的圖書，可通過其內(nèi)建的一鍵式編譯整本書的插件(build)實現(xiàn)。

2.2 快速排版的思路

1. 由rmarkdown完成整個書稿的寫作;

2. 由_output.yml完成不同形式呈現(xiàn)的書稿的設計，其中bookdown::gitbook負責html形式的gitbook, bookdown::pdf_book 負責pdf形式的電子書（由 TEXTEX 支持)；bookdown::epub_book負責epub電子書. 部分針對書稿簡單設置可放在index.Rmd文件的yml頭部(具體放在前面兩組三個短線---之間);

3. 書稿按章節(jié)進行拆分，借助js支持的html快速生成書稿的初稿，最后再進行整合，根據(jù)需要通過Build插件完成gitbook, pdf_book, epub的構建;

4. 借助mathjax處理數(shù)學公式的渲染;

   盡快可通過聯(lián)網(wǎng)由cdn上的mathjax.js進行渲染，但速度隨因公式的增加，渲染變得很慢，甚至出錯。mathjax的本地化是提速的主要解決方案.

5. 重點做好章節(jié)、數(shù)學公式、表格、圖形、定理、文獻等浮動對象的處理，在編寫過程中及時做好標簽設定與引用，見2.6節(jié)的匯總表格及后續(xù)各章的介紹與示例.

2.3 書的基本設置

一本用bookdown管理的書， 一般放置在某個子目錄下，并作為一個RStudio項目(project)用RStudio管理。該目錄中的所有的文本文件都要使用UTF-8編碼。

2.3.1 index.Rmd文件

一本bookdown書， 一般都需要有一個index.Rmd文件， 這是最后生成的網(wǎng)站的主頁的原始文件. 這個文件的開始是YAML元數(shù)據(jù)部分, 進行全書的有關設置，包括標題、作者、日期及影響全書的一些選項等，放在三個減號組成的兩行之間。然后寫一些這本書的說明，如書的前言部分。index.Rmd中YAML元數(shù)據(jù)部分的一個例子如下：

title: "bookdown書稿模板"
author: "湯銀才"
date: "2021-07-25"
documentclass: book
bibliography: [myrefs.bib]
biblio-style: apa
link-citations: yes
site: bookdown::bookdown_site
description: "bookdown寫書體驗非常好."

注意:

1. site選項很重要， 一定要有， site: bookdown::bookdown_site使得RStudio能辨認這是一個bookdown圖書項目， 從而為其生成一鍵編譯的build快捷方式；
2. 在bookdown項目中與index.Rmd同級的所有.Rmd文件都自動作為書的一章，其好處是作者可以任意地增刪章節(jié)，編譯整本書時將按照文件名的字典序依次進行。實際上， 也可以在_output.yml文件中設置一項rmd_files， 列出所有需要作為一章的文件，并以列出次序編譯；
3. 在index.Rmd的元數(shù)據(jù)中也可以指定一些 LATEX 的選項, 例如

fontsize: 12pt
indent: true
linestretch: 2.0
link-citations: yes
colorlinks: yes
lot: true
lof: true
geometry:
- a4paper
- tmargin=2.5cm
- bmargin=2.5cm
- lmargin=3.5cm
- rmargin=2.5cm

2.3.2 _bookdown.yml文件

一個bookdown圖書項目除了index.Rmd文件之外，還有一些設置文件從index.Rmd文件的元數(shù)據(jù)部分抽離出來。一個是_bookdown.yml文件, 它存放與整本書的處理有關的YAML元數(shù)據(jù)。例如

book_filename: "bookdown-template"
new_session: yes
language:
  label:
    fig: "圖 "
    tab: "表 "
    thm: '定理'
    def: '定義'
    exm: '例'
    proof: '證明: '
  ui:
    chapter_name: ["第 ", " 章"]

其中new_session: true設置很重要，這使得每一個Rmd文件中的R程序都在一個單獨的R會話中獨立地運行，避免了不同Rmd文件之間同名變量和同名標簽的互相干擾。book_filename是最終生成的PDF圖書或者ePub電子書的主文件名。language下可以定制一些與章節(jié)名、定理名等有關的名稱。

2.3.3 _output.yml文件

另一個設置文件是_output.yml， 用于圖書輸出格式的設置, 本小冊子的_output.yml文件內(nèi)容如下

bookdown::gitbook:
  css: css/style.css
  split_by: chapter
  includes:
    in_header: _header.html
  config:
    toc:
      collapse: subsection
      scroll_highlight: yes
      before: |
        <li><a href="./">bookdown排版模板</a></li>
      after: |
        <li><a href="https://bookdown.org" target="blank">本書由 bookdown 強力驅(qū)動</a></li>
    download: [pdf, epub]
    edit: https://github.com/yihui/bookdown-chinese/edit/master/%s
    sharing:
      github: yes
      facebook: no
  pandoc_args: [ "--csl", "apa-6th-edition-no-ampersand.csl" ]
bookdown::pdf_book:
  includes:
    in_header: latex/preamble.tex
    before_body: latex/before_body.tex
    after_body: latex/after_body.tex
  keep_tex: yes
  dev: "cairo_pdf"
  latex_engine: xelatex
  citation_package: biblatex
  template: latex/template.tex
  toc_depth: 3
  toc_unnumbered: no
  toc_appendix: yes
  quote_footer: ["\\begin{flushright}", "\\end{flushright}"]
  pandoc_args: [ "--top-level-division=chapter" ]
bookdown::epub_book:
  stylesheet: css/style.css
  pandoc_args: [ "--csl", "apa-6th-edition-no-ampersand.csl" ]

它分別對gitbook、pdf_book和epub_book三種輸出格式設置了一些輸出選項。其中一些選項是通過文件形式給出設置的，我們再補充說明一下。

1. style.css是自定義的 CSS 顯示格式，在gitbook和epub_book中使用;
2. _header.html是插入了一部分個性化的HTML代碼，其內(nèi)容將出現(xiàn)在每個生成的HTML文件的head部分。我們在此文件中給出了使用本地的Mathjax實現(xiàn)數(shù)學公式離線顯示的設置，內(nèi)容為

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  jax: ["input/TeX","output/SVG"],
  extensions: ["tex2jax.js","MathMenu.js","MathZoom.js"],
  TeX: {
    Macros: {
      bm: ["{\\boldsymbol #1}",1],
    },
    extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"]
  }
});

</script>
<script type="text/javascript"
  src="http://127.0.0.1/MathJax/MathJax.js">
</script>

其中http://127.0.0.1/MathJax/是本地服務器上Mathjax的位置。

 \frontmatter

\backmatter
7. `template.tex` 是針對`bookdown`編譯經(jīng)`pandoc`轉(zhuǎn)化生成的`tex`文件時的模板，由它生成供`latex_engine`指定的編譯方式(`xelatex`)編譯的`tex`文件. `index.Rmd`及`_output.yml`中的設置會嵌入到這個模板中，生成完整的單文檔`tex`源文件.

其他選項說明：

1. split_by: chapter: 按章分割書稿；
2. collapse: subsection: 目錄中隱藏子節(jié)(僅顯示二級標題)；
3. scroll_highlight: yes: 目錄滾動時高亮顯示，便于定位；
4. keep_tex: yes: 保留中間生成的tex源文件，便于查錯；
5. dev: "cairo_pdf": 使用cairo_pdf()生成 LATEX 編譯需要的圖片文件;
6. latex_engine: xelatex: TeX文件的排版引擎為 XeLATEX, 針對UTF-8編碼;
7. citation_package: biblatex: 文獻引用庫指定為biblatex, 另一個為natbib;
8. toc_depth: 3: 目錄提取至三級標題;
9. toc_unnumbered: no: 指定目錄編號;
10. toc_appendix: yes: 附錄添加到目錄中.

2.4 章節(jié)結(jié)構

如前所述, 除了index.Rmd文件， 項目中每個.Rmd文件都作為一章，其第一行是以一個#號和空格開頭的一級標題。

每一章可以有若干節(jié)與子節(jié)，分別用markdown的二級標題(二個#開始)和三級標題(三個#開始)編寫。bookdown的章、節(jié)、子節(jié)標題單獨成一行，其后可以添加標簽, 章節(jié)的標簽是標題后加空格，然后是大括號內(nèi)以#號開頭的標簽， 如

# 引言 {#intro}

## 關于bookdown {#bookdown}

bookdown中有二個特殊的標題：

1. 部分

內(nèi)容相近的章節(jié)可以作為一個“部分”。為此，在一個部分的第一個章節(jié)文件的章標題前面增加一行， 以# (PART) 開頭， 以{-}結(jié)尾，例如

   # (PART) bookdown中的浮動對象 {-}

2. 附錄

一本書的最后可以有附錄， 附錄的章節(jié)將顯示為A.1, B.1這樣的格式。為此， 在附錄章節(jié)的第一個文件開頭加如下的第一行標題行：

   # (APPENDIX) 附錄 {-}

   # biblatex介紹 {#biber}

2.5 書的編譯

在index.Rmd或者_bookdown.yml中設置site: bookdown::bookdown_site后， RStudio就能識別這個項目是一個bookdown項目， 這時RStudio會有一個Build按鈕，其中有Build book快捷圖標， 從下拉菜單中選擇一個輸出格式（包括gitbook、pdf_book、epub_book）， 就可以編譯整本書(見下圖)。

經(jīng)build編譯生成的圖書默認保存在_book子目錄中。

1. 對gitbook格式(即HTML網(wǎng)頁格式)， 編譯完成后會彈出一個預覽窗口， 點擊“Show in new window”按鈕可以將內(nèi)容在操作系統(tǒng)默認的網(wǎng)絡瀏覽器中打開。我們也可以用其他瀏覽器(建議使用 Google chrome 瀏覽器)打開_book子目錄中的index.html文件來查看gitbook格式的圖書。
2. 對于pdf_book格式，如果成功編譯(#fn4 "4")， 也會彈出一個PDF預覽窗口?？梢栽?code style="font-size: 14px;border-radius: 4px;font-family: "Operator Mono", Consolas, Monaco, Menlo, monospace;word-break: break-all;color: rgb(9, 41, 29);background-color: rgb(233, 240, 252);padding: 3px;margin: 3px;">_book子目錄中找到這個PDF文件。
3. 對于epub_book格式，如果成功編譯，會在操作系統(tǒng)默認的ePub軟件(如蘋果電腦的book)中打開,并在_book子目錄中找到這個ePub文件。

2.6 浮動對象標簽與引用匯總

注：

1. 定理泛指定理類，包括定理(thm)、引理(lem)、推論(cor)、命題(prp)、設想(cnj)、定義(def)、例子(exm)、習題(exr)等, 其中括號中是引用時的前綴(prefix);
2. 文本標簽在單獨一行中設定，可用在表格與圖形的caption中引用，即在 fig.caption, tab.caption選項的設置中引用；
3. 定理類環(huán)境標簽前綴的漢化可在_bookdown.yml中通過language進行，例如

language:
  label:
    fig: "圖 "
    tab: "表 "
    thm: '定理'
    def: '定義'
    exm: '例'