07-tools.Rmd

\cleardoublepage 

# (APPENDIX) 附录 {-}

# 软件工具 {#software-tools}

对于不熟悉如何使用 R Markdown 的依赖软件包的人，我们将简要介绍这些软件包的安装和维护。

## R 和 R 软件包

你能够从任何一个 CRAN (the Comprehensive R Archive Network) 镜像站中下载并安装 R，例如 <https://cran.rstudio.com>。请注意每年都会有一些 R 的新版本发布，你可能需要偶尔进行升级。

为了安装 **bookdown** 包，你可以在 R 中输入：

```{r eval=FALSE}
install.packages("bookdown")
```

这将安装所有必需的 R 包。如果你不太关心这些包是否真的会被用来编译你的书籍（例如 **htmlwidgets**），也可以选择安装所有可选的包：

```{r eval=FALSE}
install.packages("bookdown", dependencies = TRUE)
```

如果你想体验 GitHub 上 **bookdown** 的开发版本，需要首先安装 **devtools**：

```{r eval=FALSE}
if (!requireNamespace('devtools')) install.packages('devtools')
devtools::install_github('rstudio/bookdown')
```

R 包也经常在 CRAN 或 GitHub 上不断更新，所以你可能需要偶尔更新它们：

```{r eval=FALSE}
update.packages(ask = FALSE)
```

尽管不是必需的，但当你从事与 R 相关的项目时，使用 RStudio IDE 能够使很多事情变得更加简单。你可以从 <https://www.posit.co> 下载 RStudio IDE。

## Pandoc

R Markdown 文档 (`*.Rmd`) 首先会通过 **knitr** 包编译成 Markdown (`*.md`)，然后 Markdown 再通过 Pandoc 编译成其他输出格式（如 LaTeX 或 HTML）。\index{Pandoc}整个过程是由 **rmarkdown** 包自动完成的。你不需要额外安装 **knitr** 或 **rmarkdown**，因为它们是 **bookdown** 的依赖包，在安装 **bookdown** 时会自动安装。然而，Pandoc 并不是 R 软件包，因此不会在安装 **bookdown** 时自动安装。你可以参考 Pandoc 主页 (<http://pandoc.org>) 上的安装说明来安装 Pandoc，但如果你使用 RStudio IDE，则不需要额外安装 Pandoc，因为 RStudio 已经包含了一个 Pandoc 的副本。你可以通过以下方式查看 Pandoc 版本号：

```{r collapse=TRUE}
rmarkdown::pandoc_version()
```

如果你发现这个版本太低了，并且一些 Pandoc 功能特性只在更高版本中提供，你可以安装更高版本的 Pandoc，之后 **rmarkdown** 将会调用更高版本的 Pandoc，而不是内置的版本。

## LaTeX

只有当你想要将书籍输出为 PDF 时，你才需要 LaTeX\index{LaTeX}。你可以通过访问 <https://www.latex-project.org/get/> 来获取更多关于 LaTeX 及其安装的信息，但是我们强烈推荐你安装名为 [TinyTeX](https://yihui.org/tinytex/) 的轻量级跨平台 LaTeX 发行版，它是基于 TeX Live 构建的。TinyTeX 能够通过 R 包 **tinytex** 轻松安装（安装 **bookdown** 时将自动安装）：

```{r, eval=FALSE}
tinytex::install_tinytex()
```

使用 TinyTeX，你应该永远不会看见这样的错误信息：

```latex
! LaTeX Error: File `titling.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name: 
! Emergency stop.
<read *> 
         
l.107 ^^M

pandoc: Error producing PDF
Error: pandoc document conversion failed with error 43
Execution halted
```

上面的错误信息表示你使用了一个包含 `titling.sty` 文件的 LaTeX 包，但并没有安装该软件包。LaTeX 包名通常是 `*.sty` 的格式，因此在本例中，你可以尝试安装 `titling` 包。如果你在 R Markdown 中使用 TinyTeX，缺少的 LaTeX 包将会自动安装，因此无需担心此类问题。

LaTeX 发行版和其软件包也会不时进行更新，你可以考虑更新它们，特别是当遇到 LaTeX 问题时。你可以通过以下方式查看 LaTeX 发行版的版本：

```{r include=FALSE}
res <- base::system('pdflatex --version', intern = TRUE)
res <- paste("## ", res)
res <- paste0(res, collapse = "\n")
```

```r
system('pdflatex --version')
`r res`
```

你可以运行以下代码来更新 TinyTeX：

```{r eval=FALSE}
tinytex::tlmgr_update()
```

随着时间的推移，你可能也需要升级 TinyTeX（否则你无法安装或更新任何 LaTeX 软件包），在这种情况下你需要重新安装 TinyTeX：

```{r eval=FALSE}
tinytex::reinstall_tinytex()
```