R沟通｜Bookdown中文书稿写作手册（中）
本教程來自華東師范大學湯銀才教授，本人已授權。為了獲得更好的閱讀體驗，可在文末直達原文網站。
第 2 章 bookdown速覽
這是第 2 章的內容，概要性地講解基于bookdown拓展包進行圖書排版的整體思路與實現方式.
2.1 關于bookdown
bookdown擴展包 (https://github.com/rstudio/bookdown) 是繼knitr和rmarkdown擴展包之后， 另一個增強markdown格式的擴展， 使得Rmd格式可以支持公式、定理、圖表、文獻自動編號和引用等適用于編寫書籍的功能。在bookdown的管理下一本書的內容可以按章節分解成多個Rmd文件， 其中可以包含可執行的R代碼， R代碼生成的統計匯總結果、表格、圖形可以自動插入到生成的內容中， 表格和圖形可以是浮動排版的。書的輸出格式包括支持gitbook格式的網頁圖書， 也可以經 LATEX 編譯器轉換的PDF圖書，還可以生成ePub等格式的電子書。建議使用RStudio集成環境來編輯、管理和生成這樣的圖書，可通過其內建的一鍵式編譯整本書的插件(build)實現。
2.2 快速排版的思路
由rmarkdown完成整個書稿的寫作;
由_output.yml完成不同形式呈現的書稿的設計，其中bookdown::gitbook負責html形式的gitbook, bookdown::pdf_book 負責pdf形式的電子書（由 TEXTEX 支持)；bookdown::epub_book負責epub電子書. 部分針對書稿簡單設置可放在index.Rmd文件的yml頭部(具體放在前面兩組三個短線---之間);
書稿按章節進行拆分，借助js支持的html快速生成書稿的初稿，最后再進行整合，根據需要通過Build插件完成gitbook, pdf_book, epub的構建;
借助mathjax處理數學公式的渲染;
盡快可通過聯網由cdn上的mathjax.js進行渲染，但速度隨因公式的增加，渲染變得很慢，甚至出錯。mathjax的本地化是提速的主要解決方案.
重點做好章節、數學公式、表格、圖形、定理、文獻等浮動對象的處理，在編寫過程中及時做好標簽設定與引用，見2.6節的匯總表格及后續各章的介紹與示例.
2.3 書的基本設置
一本用bookdown管理的書， 一般放置在某個子目錄下，并作為一個RStudio項目(project)用RStudio管理。該目錄中的所有的文本文件都要使用UTF-8編碼。
2.3.1 index.Rmd文件
一本bookdown書， 一般都需要有一個index.Rmd文件， 這是最后生成的網站的主頁的原始文件. 這個文件的開始是YAML元數據部分, 進行全書的有關設置，包括標題、作者、日期及影響全書的一些選項等，放在三個減號組成的兩行之間。然后寫一些這本書的說明，如書的前言部分。index.Rmd中YAML元數據部分的一個例子如下：
title:?"bookdown書稿模板" author:?"湯銀才" date:?"2021-07-25" documentclass:?book bibliography:?[myrefs.bib] biblio-style:?apa link-citations:?yes site:?bookdown::bookdown_site description:?"bookdown寫書體驗非常好."注意:
site選項很重要， 一定要有， site: bookdown::bookdown_site使得RStudio能辨認這是一個bookdown圖書項目， 從而為其生成一鍵編譯的build快捷方式；
在bookdown項目中與index.Rmd同級的所有.Rmd文件都自動作為書的一章，其好處是作者可以任意地增刪章節，編譯整本書時將按照文件名的字典序依次進行。實際上， 也可以在_output.yml文件中設置一項rmd_files， 列出所有需要作為一章的文件，并以列出次序編譯；
在index.Rmd的元數據中也可以指定一些 LATEX 的選項, 例如
2.3.2 _bookdown.yml文件
一個bookdown圖書項目除了index.Rmd文件之外，還有一些設置文件從index.Rmd文件的元數據部分抽離出來。一個是_bookdown.yml文件, 它存放與整本書的處理有關的YAML元數據。例如
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下可以定制一些與章節名、定理名等有關的名稱。
2.3.3 _output.yml文件
另一個設置文件是_output.yml， 用于圖書輸出格式的設置, 本小冊子的_output.yml文件內容如下
bookdown::gitbook:css:?css/style.csssplit_by:?chapterincludes:in_header:?_header.htmlconfig:toc:collapse:?subpscroll_highlight:?yesbefore:?|<li><a?href="./">bookdown排版模板</a></li>after:?|<li><a?href="https://bookdown.org"?target="blank">本書由?bookdown?強力驅動</a></li>download:?[pdf,?epub]edit:?https://github.com/yihui/bookdown-chinese/edit/master/%ssharing:github:?yesfacebook:?nopandoc_args:?[?"--csl",?"apa-6th-edition-no-ampersand.csl"?] bookdown::pdf_book:includes:in_header:?latex/preamble.texbefore_body:?latex/before_body.texafter_body:?latex/after_body.texkeep_tex:?yesdev:?"cairo_pdf"latex_engine:?xelatexcitation_package:?biblatextemplate:?latex/template.textoc_depth:?3toc_unnumbered:?notoc_appendix:?yesquote_footer:?["\\begin{flushright}",?"\\end{flushright}"]pandoc_args:?[?"--top-level-division=chapter"?] bookdown::epub_book:stylesheet:?css/style.csspandoc_args:?[?"--csl",?"apa-6th-edition-no-ampersand.csl"?]它分別對gitbook、pdf_book和epub_book三種輸出格式設置了一些輸出選項。其中一些選項是通過文件形式給出設置的，我們再補充說明一下。
style.css是自定義的 CSS 顯示格式，在gitbook和epub_book中使用;
_header.html是插入了一部分個性化的HTML代碼，其內容將出現在每個生成的HTML文件的head部分。我們在此文件中給出了使用本地的Mathjax實現數學公式離線顯示的設置，內容為
其中http://127.0.0.1/MathJax/是本地服務器上Mathjax的位置。
3.apa-6th-edition-no-ampersand.csl 是gitbook和epub_book處理文獻使用的風格文件;
4.preamble.tex是處理(編譯)bookdown文件經pandoc轉化生成的tex文件時導言區需要額外的宏包和設置;
5. before_body.tex 是tex書稿類正文前面的設置，最基本的是
?\frontmatter6.?after_body.tex 是tex書稿類正文之后的設置，最基本的是
\backmatter 7.?`template.tex`?是針對`bookdown`編譯經`pandoc`轉化生成的`tex`文件時的模板，由它生成供`latex_engine`指定的編譯方式(`xelatex`)編譯的`tex`文件.?`index.Rmd`及`_output.yml`中的設置會嵌入到這個模板中，生成完整的單文檔`tex`源文件.其他選項說明：
split_by: chapter: 按章分割書稿；
collapse: subp: 目錄中隱藏子節(僅顯示二級標題)；
scroll_highlight: yes: 目錄滾動時高亮顯示，便于定位；
keep_tex: yes: 保留中間生成的tex源文件，便于查錯；
dev: "cairo_pdf": 使用cairo_pdf()生成 LATEX?編譯需要的圖片文件;
latex_engine: xelatex: TeX文件的排版引擎為 XeLATEX, 針對UTF-8編碼;
citation_package: biblatex: 文獻引用庫指定為biblatex, 另一個為natbib;
toc_depth: 3: 目錄提取至三級標題;
toc_unnumbered: no: 指定目錄編號;
toc_appendix: yes: 附錄添加到目錄中.
2.4 章節結構
如前所述, 除了index.Rmd文件， 項目中每個.Rmd文件都作為一章，其第一行是以一個#號和空格開頭的一級標題。
每一章可以有若干節與子節，分別用markdown的二級標題(二個#開始)和三級標題(三個#開始)編寫。bookdown的章、節、子節標題單獨成一行，其后可以添加標簽, 章節的標簽是標題后加空格，然后是大括號內以#號開頭的標簽， 如
#?引言?{#intro}##?關于bookdown?{#bookdown}bookdown中有二個特殊的標題：
1. 部分
內容相近的章節可以作為一個“部分”。為此，在一個部分的第一個章節文件的章標題前面增加一行， 以# (PART) 開頭， 以{-}結尾，例如
???#?(PART)?bookdown中的浮動對象?{-}2. 附錄
一本書的最后可以有附錄， 附錄的章節將顯示為A.1, B.1這樣的格式。為此， 在附錄章節的第一個文件開頭加如下的第一行標題行：
???#?(APPENDIX)?附錄?{-}#?biblatex介紹?{#biber}2.5 書的編譯
在index.Rmd或者_bookdown.yml中設置site: bookdown::bookdown_site后， RStudio就能識別這個項目是一個bookdown項目， 這時RStudio會有一個Build按鈕，其中有Build book快捷圖標， 從下拉菜單中選擇一個輸出格式（包括gitbook、pdf_book、epub_book）， 就可以編譯整本書(見下圖)。
R Bookdown編譯界面.經build編譯生成的圖書默認保存在_book子目錄中。
對gitbook格式(即HTML網頁格式)， 編譯完成后會彈出一個預覽窗口， 點擊“Show in new window”按鈕可以將內容在操作系統默認的網絡瀏覽器中打開。我們也可以用其他瀏覽器(建議使用 Google chrome 瀏覽器)打開_book子目錄中的index.html文件來查看gitbook格式的圖書。
對于pdf_book格式，如果成功編譯(#fn4 "4")， 也會彈出一個PDF預覽窗口?？梢栽赺book子目錄中找到這個PDF文件。
對于epub_book格式，如果成功編譯，會在操作系統默認的ePub軟件(如蘋果電腦的book)中打開,并在_book子目錄中找到這個ePub文件。
2.6 浮動對象標簽與引用匯總
| 標題 | (# label) | \@ref(label) |
| 公式 | (\#eq:label) | \@ref(eq:label) |
| 圖形 | label="label" | \@ref(fig:label) |
| 表格 | label="label" | \@ref(tab:label) |
| 定理 | label="label" | \@ref(prefix:label) |
| 文本 | (ref:label) | (ref:label) |
| 文獻 | biblabel | @biblabel |
注：
定理泛指定理類，包括定理(thm)、引理(lem)、推論(cor)、命題(prp)、設想(cnj)、定義(def)、例子(exm)、習題(exr)等, 其中括號中是引用時的前綴(prefix);
文本標簽在單獨一行中設定，可用在表格與圖形的caption中引用，即在 fig.caption, tab.caption選項的設置中引用；
定理類環境標簽前綴的漢化可在_bookdown.yml中通過language進行，例如
往期精品(點擊圖片直達文字對應教程)
機器學習
后臺回復“生信寶典福利第一波”或點擊閱讀原文獲取教程合集
總結
以上是生活随笔為你收集整理的R沟通｜Bookdown中文书稿写作手册（中）的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 双核心四线程编辑
- 下一篇： 串行并行程序在效率上的简单比较