【翻译】如何自出版一本书：定制 bookdown

本文翻译自 Pablo Casas 的博客 How to self publish a book: customizing Bookdown，感谢作者的授权。

原始链接：https://blog.datascienceheroes.com/how-to-self-publish-a-book-customizing-bookdown/

This post is translated form Pablo Casas’s post — How to self publish a book: customizing Bookdown. Thanks to the author for authorization.

original link: https://blog.datascienceheroes.com/how-to-self-publish-a-book-customizing-bookdown/

【翻译】如何自出版一本书：定制 bookdown

本文和前一篇文章——《如何自出版一本书：一份资源清单》相关联。本文围绕 bookdown 展开，以及我在创作《Data Science Live Book》的过程中发现的非标准定制化技巧。

Github 上的本书：https://github.com/pablo14/data-science-live-book

如果你没有打算写一本书、一份手册或任何其他类型的文件，这似乎不太重要。但是，如果你开始写作，谷歌可能会带你到这里来寻找答案。

bookdown 的第一步

这不是一篇介绍性的文章。但是，要了解 bookdown 的话，请从下面的内容开始：

• bookdown 官网教材（由 bookdown 创建）；
• What is R markdown?（RStudio）；
• A minimum reproducible example，我建议你 clone 下来并运行（这是输出结果）

亚马逊 Kindle 格式

亚马逊图书的扩展名是 .mobi，而 bookdown 提供的格式是 .epub，你可以从下面的链接下载转换软件：

https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211

如果 epub 版本的书和程序 kindlegen 处于同一路径，转换格式只需输入下面的命令：./kindlegen my-amazing-book.epub

这将产生新的文件：my-amazing-book.mobi.

我知道 Calibre 也可以将 epub 转换到 mobi。但保险起见，我建议你用亚马逊的 kindlegen。Calibre 看电子书很有用，它是免费的。

创建书籍

首先，获得我用来创建 PDF 和 html 的脚本，在这里。

我用 RStudio 按钮（在 bookdown::epub_book 选项）创建 epub。

_bookdown.yml

在此文件中，你可以定义要处理的文件，以及显示页面的顺序。

默认是运行所有页面。但是，如果这本书很大，那么它会运行很多不必要的代码。如你所见，我在调试时使用了两条注释。

请注意 new_session: yes：要看最新运行的话，这很重要。

注意行宽

虽然我们通常不会考虑行宽，即一行中有多少个字符，但如果有个字符超出你定义的页面格式的边距，亚马逊将不会发布该书。

用 formatR（谢益辉开发的另一个包）来解救你！为什么是用它？因为它能自动格式化 R 代码。

是的，它总是会重新安排代码以“适配”行宽要求（备注 1）。Hurray！

在线应用：https://yihui.shinyapps.io/formatR/

备注 1：然而，在某些条件下，它并不是按照我们想要的方式工作（但能预见得到）。它使用了 R base 包中的 deparse 函数。

由于缺少对技术细节的了解，我不得不使用 dirty-while(1) 的 hack 方式修改 formatR，因为 deparse 函数并不能按照我想要的方式处理行宽。

更多技术信息：https://github.com/yihui/formatR/pull/71

我 fork 了 formatR 以实现这个功能。我不保证它在所有情形下都能工作：https://github.com/pablo14/formatR

我花了 30 个小时来修改它，我希望它能帮到你，哪怕 1 分钟。

重点：检查下一节中的参数 width.cutoff=56 和 options("width"=56)。

写在每个 .Rmd 文件的开头

这是我写下的：

```{r include = FALSE}
if(!knitr:::is_html_output())
{
    options("width"=56)
    knitr::opts_chunk$set(
        tidy.opts=list(width.cutoff=56, indent = 2),
        tidy = TRUE)
    knitr::opts_chunk$set(fig.pos = 'H')
}
```

这将在输出 PDF 的情况下运行。这为文件中的所有块设置了全局选项，但我们可以覆盖每个块的行为。

现在，我不记得对于 width.cutoff=56 来说 options("width"=56) 是否是冗余的，但根据书本的大小，我的最大行宽是 56 个字符。

indent = 2：缩进两个空格。

tidy=TRUE 让 formatR 能够产生漂亮且标准的代码布局。记住，我使用的是自己 fork 的 formatR。

当宽度修正不起作用的时候，你需要在 Rmd（不是 md！）中手动修改它。这时，你需要为所有手动修正的块设置 tidy=FALSE：

```{r, tidy=FALSE}
print("bla bla bla * 1000")
```

例如，本书的一个 .Rmd 文件：

可以看到 tidy=FALSE，并且每行最宽 56 个字符。亚马逊和我都可以保证这一点。

这是这一段的 web 在线版：https://livebook.datascienceheroes.com/exploratory-data-analysis.html#selecting_best_vars_mic

这是 PDF 版：

bookdown 的功能真是太赞了！

index.Rmd 中的一些参数

links-as-notes: true

如果你想拥有图书的可打印版本，请使用此选项。它会将所有超链接转换为脚注（因为你无法单击纸张）。

一个很好的功能：当我们引用书中的章节时，页码不会出现在脚注中或参考位置旁边。有关示例，请参见数据准备章节（54 页）中的更多内容。

linestretch: 1.15

如果 PDF 中句子间的行距非常小，请使用此参数。它会为你的段落提供一些空间。;)

图片

图片位置

knitr::opts_chunk$set(fig.pos = 'H')，记住，这句放在 Rmd 文件的开头。

参数 fig.pos='H'（加上另一个）强制所有图片出现在我们画出它们的地方，否则它们将出现在页面的底部。

另一个是 out.extra=''（两个单引号），你必须为每个块定义。

接着前面的例子：

```{r importance-variable-ranking, fig.width=6, fig.height=4.5,
tidy=FALSE, fig.cap="Correlation using information theory",
out.extra=''}
```

更多关于图片位置的信息：https://stackoverflow.com/questions/42486617/knitr-ignoring-fig-pos

当你添加图片时，像这样做是不必要的：

knitr::include_graphics(
    "exploratory_data_analysis/mic_mutual_info.png")

图片说明与索引

fig.cap：为图片添加说明，以及一个自增长的数字（例如 1.18）：

图片大小

从上一个例子：fig.width=6 和 fig.height=4.5 以 RStudio 中相同的方式定义图片大小：如果你减小它，那么数字将变得更大（译注：可能是笔误？）

图片的大小取决于你所画的图。

还有其他方式定义图片大小，例如 out.width 和 out.height，按照屏幕的百分比或像素调整图片大小。请参考官方文档：https://bookdown.org/yihui/bookdown/figures.html

长 url 的换行

当引用参考文献的时候，一条长 url 会超出边界，要用下面的方式修正：

在 template.tex 添加：\Urlmuskip=0mu plus 1mu\relax

对于目录中的 url，我不知道怎么换行。我笨拙地 hack 了一下：使用谷歌短 url 服务，例如 https://goo.gl/2TrDgN（现在已经失效了），所以试试选择其他服务，例如 tinyurl。

书本大小

我开始的时候用 A4 格式的纸，因为这是默认的。当书快完成的时候，我才发现它和一只 7 岁大的喵喵一样宽：

接受了谷歌的神谕之后，我得知科技类图书的“标准大小”是 6 x 9 英寸，或 15.24 x 22.86 cm。

再一次，这可以在 tempated.tex 中定义：

\usepackage[paperwidth=6in, paperheight=9in]{geometry}

这样一来，你必须重新检查所有行宽。

结语

我真的希望我能鼓励你在书中写下你自己的故事。对于你计划发布的某些资料，如果你想得到其他意见，请与我们联系。

不要害羞，从只有几个页面的网站开始，或者在 Rpubs 还有 Github Pages 上发帖子。享受你所做的事，并让其成长。

感谢阅读！