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

0.1 Why read this book

Can we write a book in one source format, and generate the output to multiple formats? Traditionally books are often written with LaTeX or Microsoft Word. Either of these tools will make writing books a one-way trip and you cannot turn back: if you choose LaTeX, you typically end up only with a PDF document; if you work with Word, you are likely to have to stay in Word forever, and may also miss the many useful features and beautiful PDF output from LaTeX.

我们能以一种源格式(source format）编写一本书，然后生成多种格式的输出吗?传统上，书籍通常是用LaTeX或微软Word编写的。这两种工具都可以让你写书成为一种单向路，你无法回滚:如果你选择LaTeX，你通常只能得到一个PDF文档;如果你使用Word，你很可能会永远停留在Word，并可能会错过LaTeX的许多有用的功能及漂亮的PDF输出。

Can we focus on writing the content without worrying too much about typesetting? There seems a natural contradiction between content and appearance, and we always have to balance our time spent on these two aspects. No one can have a cake and eat it too, but it does not mean we cannot have a half and eat a half. We want our book to look reasonably pretty, and we also want to focus on the content. One possibility is to give up PDF temporarily, and what you may have in return is a pretty preview of your book as HTML web pages. LaTeX is an excellent typesetting tool, but you can be easily buried in the numerous LaTeX commands and typesetting details while you are working on the book. It is just so hard to refrain from previewing the book in PDF, and unfortunately also so common to find certain words exceed the page margin, certain figures float to a random page, five or six stray words at the very end of a chapter proudly take up a whole new page, and so on. If the book is to be printed, we will have to deal with these issues eventually, but it is not worth being distracted over and over again while you are writing the content of the book. The fact that the Markdown syntax is simpler and has fewer features than LaTeX also helps you focus on the content. Do you really have to define a new command like \myprecious{} that applies \textbf{\textit{\textsf{}}} to your text? Does the letter “R” have to be enclosed in \proglang{} when readers can easily figure out it stands for the R language? It does not make much difference whether everything, or nothing, needs the reader’s attention.

我们能集中精力写内容而不太担心排版吗?内容和外观之间似乎存在着一种自然的矛盾，我们总是需要在这两个方面上平衡我们所花费的时间。没有人可以既拥有一块蛋糕又吃掉它，但这并不意味着我们不能既有一半又吃一半。我们希望我们的书看起来相当漂亮，我们也希望写作时能聚焦于内容上。其中一种可能是暂时放弃PDF，但作为回报，你可能得到一个漂亮的HTML网页来预览你的书。LaTeX是一个优秀的排版工具，但是当你在写这本书的时候，你很容易被大量LaTeX命令和排版细节所淹没。这样很难避免在PDF预览这本书时发现某些词超过页面边缘,某些图标浮动到其他页,章末的五六的词占据一个全新的页面,等等。如果书要印刷，我们最终将不得不处理这些问题，但它不值得在你写书的内容时让你一遍又一遍地分心。Markdown语法比LaTeX更简单，特性也更少，这一事实也有助于您关注内容。您是否真的必须定义像 \myprecious{}这样的新命令，它将\textbf{\textit{\textsf{}}} 应用于您的文本？字母“R”必须被包含在\proglang{}中吗?读者很容易就能知道它代表R语言。究竟什么都需要读者注意，还是什么都不需要，这并没有多大区别。

Can readers interact with examples in our book as they read it? The answer is certainly no if the book is printed on paper, but it is possible if your book has an HTML version that contains live examples, such as Shiny applications (https://shiny.rstudio.com) or HTML widgets (https://htmlwidgets.org). For example, readers may immediately know what happens if they change certain parameters of a statistical model.

读者在阅读时能与书中的例子互动吗?如果书籍是纸质的，答案当然是否定的，但是如果您的书籍有一个包含实际示例的HTML版本，比如shiny的应用程序(https://shiny.rstudio.com)或HTML小部件(https://htmlwidgets.org)，则是可能的。例如，读者可以立即知道如果他们改变一个统计模型的某些参数会发生什么。

Can we get feedback and even contributions from readers as we develop the book? Traditionally the editor will find a small number of anonymous reviewers to review your book. Reviewers are often helpful, but you may still miss the wisdom of more representative readers. It is too late after the first edition is printed, and readers may need to wait for a few years before the second edition is ready. There are some web platforms that make it easy for people to provide feedback and contribute to your projects. GitHub (https://github.com) is one prominent example. If anyone finds a typo in your book, he/she can simply correct it online and submit the change back to you for your approval. It is a matter of clicking a button to merge the change, with no questions asked or emails back and forth. To be able to use these platforms, you need to learn the basics of version control tools like GIT, and your book source files should be in plain text.

当我们开发这本书时，我们能从读者那里得到反馈甚至贡献吗?传统上，编辑会找一些匿名的评论家来评论你的书。评论员通常是有帮助的，但你可能仍然没有看到更有代表性的读者的智慧。第一版印刷后就太晚了，读者可能需要等几年才能出版第二版。有一些网络平台可以让人们很容易地为你的项目提供反馈和贡献。GitHub (https://github.com)就是一个突出的例子。如果有人在你的书中发现了拼写错误，他/她可以在线修改并将更改提交给你，让你批准。只需点击一个按钮就可以合并更改，无需询问问题或来回发送电子邮件。为了能够使用这些平台，您需要学习像GIT这样的版本控制工具的基础知识，并且您的图书源文件应该是纯文本的。

The combination of R (https://www.r-project.org), Markdown, and Pandoc (http://pandoc.org) makes it possible to go from one simple source format (R Markdown) to multiple possible output formats (PDF, HTML, EPUB, and Word, etc.). The bookdown package is based on R Markdown, and provides output formats for books and long-form articles, including the GitBook format, which is a multi-page HTML output format with a useful and beautiful user interface. It is much easier to typeset in HTML than LaTeX, so you can always preview your book in HTML, and work on PDF after the content is mostly done. Live examples can be easily embedded in HTML, which can make the book more attractive and useful. R Markdown is a plain-text format, so you can also enjoy the benefits of version control, such as collaborating on GitHub. We have also tried hard to port some important features from LaTeX to HTML and other output formats, such as figure/table numbering and cross-references.

R (https://www.r-project.org)、Markdown和Pandoc (http://pandoc.org)的组合使得从一个简单的源格式(R Markdown)到多种可能的输出格式(PDF、HTML、EPUB和Word等)成为可能。bookdown包基于R Markdown，并为书籍和长篇文章提供输出格式，包括GitBook格式(它是一种多页HTML输出格式，具有有用和漂亮的用户界面)。用HTML排版要比LaTeX容易得多，所以你总是可以用HTML预览你的书，然后在内容基本完成后再输出为PDF。活生生的例子可以很容易地嵌入到HTML中，这可以使这本书更有吸引力和有用。R Markdown是一种纯文本格式，所以你也可以享受版本控制的好处，比如在GitHub上协作。我们还努力将LaTeX的一些重要特性移植到HTML和其他输出格式，比如图/表编号和交叉引用。

In short, you just prepare a few R Markdown book chapters, and bookdown can help you turn them into a beautiful book.

简而言之，你只需要准备一些R Markdown作为书中的章节，而bookdown 会将这些Rmarkdown变成一本美丽的书。