专栏首页庄闪闪的R语言手册R沟通|Bookdown中文书稿写作手册(中)

R沟通|Bookdown中文书稿写作手册(中)

第 2 章 bookdown速览

这是第 2 章的内容,概要性地讲解基于bookdown拓展包进行图书排版的整体思路与实现方式.

2.1 关于bookdown

bookdown扩展包 (https://github.com/rstudio/bookdown) 是继knitrrmarkdown扩展包之后, 另一个增强markdown格式的扩展, 使得Rmd格式可以支持公式、定理、图表、文献自动编号和引用等适用于编写书籍的功能。在bookdown的管理下一本书的内容可以按章节分解成多个Rmd文件, 其中可以包含可执行的R代码, R代码生成的统计汇总结果、表格、图形可以自动插入到生成的内容中, 表格和图形可以是浮动排版的。书的输出格式包括支持gitbook格式的网页图书, 也可以经 LATEX 编译器转换的PDF图书,还可以生成ePub等格式的电子书。建议使用RStudio集成环境来编辑、管理和生成这样的图书,可通过其内建的一键式编译整本书的插件(build)实现。

2.2 快速排版的思路

  1. rmarkdown完成整个书稿的写作;
  2. _output.yml完成不同形式呈现的书稿的设计,其中bookdown::gitbook负责html形式的gitbook, bookdown::pdf_book 负责pdf形式的电子书(由 TEXTEX 支持);bookdown::epub_book负责epub电子书. 部分针对书稿简单设置可放在index.Rmd文件的yml头部(具体放在前面两组三个短线---之间);
  3. 书稿按章节进行拆分,借助js支持的html快速生成书稿的初稿,最后再进行整合,根据需要通过Build插件完成gitbook, pdf_book, epub的构建;
  4. 借助mathjax处理数学公式的渲染; 尽快可通过联网由cdn上的mathjax.js进行渲染,但速度随因公式的增加,渲染变得很慢,甚至出错。mathjax的本地化是提速的主要解决方案.
  5. 重点做好章节、数学公式、表格、图形、定理、文献等浮动对象的处理,在编写过程中及时做好标签设定与引用,见2.6节的汇总表格及后续各章的介绍与示例.

2.3 书的基本设置

一本用bookdown管理的书, 一般放置在某个子目录下,并作为一个RStudio项目(project)用RStudio管理。该目录中的所有的文本文件都要使用UTF-8编码。

2.3.1 index.Rmd文件

一本bookdown书, 一般都需要有一个index.Rmd文件, 这是最后生成的网站的主页的原始文件. 这个文件的开始是YAML元数据部分, 进行全书的有关设置,包括标题、作者、日期及影响全书的一些选项等,放在三个减号组成的两行之间。然后写一些这本书的说明,如书的前言部分。index.RmdYAML元数据部分的一个例子如下:

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文件都自动作为书的一章,其好处是作者可以任意地增删章节,编译整本书时将按照文件名的字典序依次进行。实际上, 也可以在_output.yml文件中设置一项rmd_files, 列出所有需要作为一章的文件,并以列出次序编译;
  3. index.Rmd的元数据中也可以指定一些 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文件的元数据部分抽离出来。一个是_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.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 强力驱动</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" ]

它分别对gitbookpdf_bookepub_book三种输出格式设置了一些输出选项。其中一些选项是通过文件形式给出设置的,我们再补充说明一下。

  1. style.css是自定义的 CSS 显示格式,在gitbookepub_book中使用;
  2. _header.html是插入了一部分个性化的HTML代码,其内容将出现在每个生成的HTML文件的head部分。我们在此文件中给出了使用本地的Mathjax实现数学公式离线显示的设置,内容为
<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的位置。

3.apa-6th-edition-no-ampersand.cslgitbookepub_book处理文献使用的风格文件;

4.preamble.tex是处理(编译)bookdown文件经pandoc转化生成的tex文件时导言区需要额外的宏包和设置;

5. before_body.textex书稿类正文前面的设置,最基本的是

 \frontmatter

6. after_body.textex书稿类正文之后的设置,最基本的是

\backmatter
7. `template.tex` 是针对`bookdown`编译经`pandoc`转化生成的`tex`文件时的模板,由它生成供`latex_engine`指定的编译方式(`xelatex`)编译的`tex`文件. `index.Rmd`及`_output.yml`中的设置会嵌入到这个模板中,生成完整的单文档`tex`源文件.

其他选项说明:

  1. split_by: chapter: 按章分割书稿;
  2. collapse: subsection: 目录中隐藏子节(仅显示二级标题);
  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 章节结构

如前所述, 除了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快捷图标, 从下拉菜单中选择一个输出格式(包括gitbookpdf_bookepub_book), 就可以编译整本书(见下图)。

R Bookdown编译界面.

build编译生成的图书默认保存在_book子目录中。

  1. gitbook格式(即HTML网页格式), 编译完成后会弹出一个预览窗口, 点击“Show in new window”按钮可以将内容在操作系统默认的网络浏览器中打开。我们也可以用其他浏览器(建议使用 Google chrome 浏览器)打开_book子目录中的index.html文件来查看gitbook格式的图书。
  2. 对于pdf_book格式,如果成功编译(#fn4 "4"), 也会弹出一个PDF预览窗口。可以在_book子目录中找到这个PDF文件。
  3. 对于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

注:

  1. 定理泛指定理类,包括定理(thm)、引理(lem)、推论(cor)、命题(prp)、设想(cnj)、定义(def)、例子(exm)、习题(exr)等, 其中括号中是引用时的前缀(prefix);
  2. 文本标签在单独一行中设定,可用在表格与图形的caption中引用,即在 fig.caption, tab.caption选项的设置中引用;
  3. 定理类环境标签前缀的汉化可在_bookdown.yml中通过language进行,例如
language:
  label:
    fig: "图 "
    tab: "表 "
    thm: '定理'
    def: '定义'
    exm: '例'

推荐: 可以保存以下照片,在 b 站扫该二维码,或者 b 站搜索【庄闪闪】观看 Rmarkdown 系列的视频教程。Rmarkdown 视频新增两节视频(写轮眼幻灯片制作)需要视频内的文档,可在公众号回复【rmarkdown

本文分享自微信公众号 - 庄闪闪的R语言手册(Zss_R4ds),作者:汤银才

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2021-08-15

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • R沟通|Bookdown中文书稿写作手册(下)

    本教程来自华东师范大学汤银才教授,本人已授权。为了获得更好的阅读体验,可在文末直达原文网站。前两期内容见:R沟通|Bookdown中文书稿写作手册(中);R沟通...

    庄闪闪
  • R沟通|Bookdown中文书稿写作手册(上)

    今年接了 5 本与贝叶斯近似计算包INLA相关的翻译书,将由高等教育出版社出版。在准备翻译的时候,我静下来思考了一下二个问题。一是互联网时代在兼顾图书质量的同时...

    王诗翔呀
  • R沟通|Bookdown中文书稿写作手册(上)

    今年接了 5 本与贝叶斯近似计算包INLA相关的翻译书,将由高等教育出版社出版。在准备翻译的时候,我静下来思考了一下二个问题。一是互联网时代在兼顾图书质量的同时...

    庄闪闪
  • R沟通|用bookdown制作图书(1)

    R的bookdown扩展包是继knitr和rmarkdown扩展包之后, markdown格式的另一种扩展, 使得Rmd格式可以支持公式、定理、图表自动编号和引...

    庄闪闪
  • 《毕业论文新手入坑手册》分享

    我把之前公众号和专栏发布的关于毕业论文写作全过程(包含选题、文献阅读、文献分析、论文写作和答辩注意事项等)内容,集结成了一本书,并且在线发布了。

    王树义
  • 「Workshop」第十九期:Markdown与RMarkdown最佳入口

    目前对于两者的介绍网上一大堆,而且本身语法简单,上手很快,这里不会过多介绍。**本文的核心在于让读者了解这些工具以及根据需要去学习和利用它们。**这里主要为初学...

    王诗翔呀
  • 翻译|记住一些常用的R包

    原文:Some R Packages to Keep In Mind(原文见文末链接)

    庄闪闪
  • 别人的电子书,你的电子书,都在bookdown

    bookdown是著名R包作者谢益辉开发的,支持采用Rmarkdown (R代码可以运行)或普通markdown编写文档,然后编译成HTML, WORD, PD...

    生信宝典
  • 干掉 LaTeX !用BookDown写本书

    bookdown是著名R包作者谢益辉开发的,支持采用Rmarkdown (R代码可以运行)或普通markdown编写文档,然后编译成HTML, WORD, PD...

    统计学家
  • 原来Rstudio还可以这么使用,又方便了一些

    在别人的电子书,你的电子书,都在bookdown中我们讲述了bookdown用于自动化文档生成。里面涉及到一个文件Rproj用于项目管理。

    生信宝典
  • Bookdown文档生成教程

    bookdown是一款及其方便的编写技术文档或教材的工具,语法简洁,数据处理灵活。支持Rmarkdown或普通markdown通过pandoc软件转换为HTML...

    生信宝典
  • R分享|安利两个“云”办公的网站!

    最近电脑电池坏了,拿到店里维修了,自己也没有备用机。要不是有 ddl,小编就会以此为借口放个小长假 ?。玩笑可以开,但是活还是要干的。

    庄闪闪
  • 构建可重复的单细胞数据分析流程

    科学研究的过程可重复性可以说是一件不言而喻的事情:如果你提出一观点或发现一个现象,在别人那里完全重复不出来,谁知道是不是臆想呢?但是有时候重复人家的研究结论又会...

    生信技能树jimmy
  • 学习R语言,一篇文章让你从懵圈到入门

    PivotalR:用于读取Pivitol(Greenplum)和HAWQ数据库中的数据

    华章科技
  • R沟通|提升xaringan幻灯片的b格

    前面我们已经对xaringan进行详细的入门介绍:R沟通|用xaringan包制作幻灯片,并且做了一个小小的拓展:R沟通|设置xaringan主题。今天介绍下另...

    庄闪闪
  • 程序员副业那些事:聊聊出书和录视频

    或许有人会说,如果把本职工作做到极致,那么就不需要副业了,这话也有道理,因为干活的方式是相通的,如果本职都是得过且过地敷衍,那么就别再提副业了。

    用户1153489
  • R语言学习 - 入门环境Rstudio

    R语言是比较常用的统计分析和绘图语言,拥有强大的统计库、绘图库和生信分析的Bioconductor库,是学习生物信息分析的必备语言之一。 Rstudio是编辑、...

    生信宝典
  • 良心教程 | 如何在Typora中设置免费的图床

    https://github.com/Molunerfinn/PicGo/releases

    邓飞
  • 我的第一本英文技术书

    在这本书的写作过程中,我个人最大的收获应该是:当你制定了一个目标,不论这个目标开始开起来有多么的不切实际,一旦你开始细化这个目标并逐步实施,你就已经离这个目标不...

    ThoughtWorks

扫码关注云+社区

领取腾讯云代金券