In rstudio/bookdown: Authoring Books and Technical Documents with R Markdown

\cleardoublepage

(APPENDIX) Appendix {-}

Software Tools

For those who are not familiar with software packages required for using R Markdown, we give a brief introduction to the installation and maintenance of these packages.

R and R packages

R can be downloaded and installed from any CRAN (the Comprehensive R Archive Network) mirrors, e.g., https://cran.rstudio.com. Please note that there will be a few new releases of R every year, and you may want to upgrade R occasionally.

To install the bookdown package, you can type this in R:

install.packages("bookdown")

This installs all required R packages. You can also choose to install all optional packages as well, if you do not care too much about whether these packages will actually be used to compile your book (such as htmlwidgets):

install.packages("bookdown", dependencies = TRUE)

If you want to test the development version of bookdown on GitHub, you need to install devtools first:

if (!requireNamespace('devtools')) install.packages('devtools')
devtools::install_github('rstudio/bookdown')

R packages are also often constantly updated on CRAN or GitHub, so you may want to update them once in a while:

update.packages(ask = FALSE)

Although it is not required, the RStudio IDE can make a lot of things much easier when you work on R-related projects. The RStudio IDE can be downloaded from https://www.posit.co

Pandoc

An R Markdown document (*.Rmd) is first compiled to Markdown (*.md) through the knitr package, and then Markdown is compiled to other output formats (such as LaTeX or HTML) through Pandoc.\index{Pandoc} This process is automated by the rmarkdown package. You do not need to install knitr or rmarkdown separately, because they are the required packages of bookdown and will be automatically installed when you install bookdown. However, Pandoc is not an R package, so it will not be automatically installed when you install bookdown. You can follow the installation instructions on the Pandoc homepage (http://pandoc.org) to install Pandoc, but if you use the RStudio IDE, you do not really need to install Pandoc separately, because RStudio includes a copy of Pandoc. The Pandoc version number can be obtained via:

rmarkdown::pandoc_version()

If you find this version too low and there are Pandoc features only in a later version, you can install the later version of Pandoc, and rmarkdown will call the newer version instead of its built-in version.

LaTeX

LaTeX\index{LaTeX} is required only if you want to convert your book to PDF. You may see https://www.latex-project.org/get/ for more information about LaTeX and its installation, but we strongly recommend that you install the lightweight and cross-platform LaTeX distribution named TinyTeX and based on TeX Live. TinyTeX can be easily installed through the R package tinytex (which should be automatically installed when you install bookdown):

tinytex::install_tinytex()

With TinyTeX, you should never see error messages like this:

! 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

The above error means you used a package that contains titling.sty, but it was not installed. LaTeX package names are often the same as the *.sty filenames, so in this case, you can try to install the titling package. If you use TinyTeX with R Markdown, missing LaTeX packages will be installed automatically, so you never need to worry about such problems.

LaTeX distributions and packages are also updated from time to time, and you may consider updating them especially when you run into LaTeX problems. You can find out the version of your LaTeX distribution by:

res <- base::system('pdflatex --version', intern = TRUE)
res <- paste("## ", res)
res <- paste0(res, collapse = "\n")

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

To update TinyTeX, you may run:

tinytex::tlmgr_update()

From year to year, you may need to upgrade TinyTeX, too (otherwise you cannot install or update any LaTeX packages), in which case you may reinstall TinyTeX: