Reviews of Books and Teaching Materials

If you have written about statistics and included examples that are implemented in a programming language, you have struggled with the challenge of weaving together these two distinct forms of communication. Donald Knuth laid out a model of “literate programming” (1992) that prioritizes the clarity of computer code by embedding snippets of code within explanatory text. A new tool for authoring large-scale dynamic documents in this paradigm is the bookdown package, described by a book of the same name, and it stands as the most comprehensive and extensible tool available for R users. My own motivation for using literate programming tools began when I was a new instructor searching for the best way to convey materials and course notes to my students. As I began to use Rmore andmore in my classes, it became clear that I should look for avenues to includeR code and its output directly into the document so that I could avoid the dreaded (and error-prone) copying-and-pasting of figures and output back and forth to the text editor. My first attempts were with Sweave (Leisch 2002), which enables R code to be embedded directly into a LATEX document, but it proved challenging to implement certain features such as code caching and image resizing. These issues were resolved with knitr, which was described in great detail by Yihui Xie in hisDynamic Documents with R and knitr book (2013). This was a great next step, but it was limited to producing only PDF documents and I remember many hours tweaking images to make sure they appeared in the appropriate spot for my students. This was not quite there yet either. The next step was to use R Markdown (Allaire 2017), which my students were using to submit homework in HTML format. But this had limitations as well. There was no method to crossreference figures in one chapter from another chapter of the book. The figures were not numbered successively. These problems, and many others, were solved by the release of the bookdown package by Yihui Xie in 2016. In the preface, Xie writes that it should be “technically easy to write a book” and “authors should not always be distracted by typesetting details. ” I will argue throughout this review that there are some substantial technical leaps that still need to be made to get authors to use bookdown on a reasonably sized book, but that it immediately solves the problem of frequent dealing with LATEX typesetting issues by focusing on the HTML version of books instead. Chapter 1 discusses the motivation for writing the bookdown package, including a few useful features missing inMarkdown syntax. A balance is always needed to ensure that the same code produces results in different output formats (HTML, PDF, ebook, etc.). Next, there is a simple five-step process to get even a complete beginner up and running with their own basic book that they can modify for their needs. Chapter 2 is the most important chapter in the book in my opinion. It discusses the various extensions to Markdown that are included in bookdown. A run-through of the basics of Markdown syntax begins Chapter 2, leading up to showing how to include equations using LATEX-style syntax, while still working across the various output formats. Some more advanced LATEX equations are given with their corresponding code here in a way that should still be digestible to a beginner. The segue to theorem and proof environments is more challenging. These environments require a different paradigm for entering text inside chunks where a beginning R Markdown user may only be used to using chunks for R code. Chapter 2 also discusses topics that are central to creating dynamic documents. The discussion on resizing images across output formats is particularly enlightening. Finally, the important topic of including widgets is discussed in Chapter 2. The power of including an interactive shiny app that readers can connect and play with to develop concepts inside a book is incredible. These closing sections have clear examples and tips useful for beginner and intermediate R Markdown users. As Xie suggests, Chapters 1 and 2 provide the needed knowledge to solve most problems in producing a reproducible textbook. The remaining chapters are far more advanced, while still usually maintaining a conversational tone. Chapter 3 discusses the different options that go with various output formats supported, including HTML, LATEX/PDF, and ebooks. One of the challenges I had initially working with bookdownwas on specifying different options in the YAML of the _output. yml file discussed here. This is quite overwhelming for a reader to follow! In particular, the order in which different output formats are specified in the YAMLmatters. If thebookdown user would like to have a link to the PDF version of the book in the HTML format, PDF must be specified above the HTML (gitbook) format. This is not discussed in Chapter 3. The discussion on Bootstrap style in the HTML section of Chapter 3 shifts to customizing HTML output, but for a book listing “basic R Markdown knowledge” as a prerequisite, this is not at the right level. Page 58 is even harder to follow since it embeds HTML code into a long R function call. As much as I love this book, these deviations from a book designed for a beginning R Markdown author really hurt its flow. While the HTML section is far too advanced for beginners, the LATEX/PDF section is at just the right level. At just over one page of text, it does not confuse new users with a lot of LATEX code but does show how some of the choices for cross-references were derived from similar LATEX syntax and discusses briefly how customizations can be made to LATEX output via YAML options. Chapter 3 concludes with a discussion on ebook formats and how to integrate the extra features of bookdown into R Markdown documents. Chapter 4 is a short chapter discussing how to customize YAML code or the underlying template file for different output formats to tweak your outputted document(s). It is to be