Chapter 5 Making a book!

This section is heavily informed by Lucy’s beautiful blog post and accompanying toolkit.

Now that we have the bare bones of a dissertation, we can compile it for the first time.

Go to exercise 4 in Section 8.4

Recall that, for this method, the essential ingredients are:

  • your .Rmd files (chapters)
  • index.Rmd

Optional ingredients:

  • references.bib
  • templates

5.1 The workhorses

The files that will do the heavy lifting in order for your dissertation to compile as a PDF are:

  • index.Rmd contains the YAML3
  • params.tex
  • preamble.tex

index.Rmd

This contains a lot of info. You can specify different options for each output type you plan to compile. Since we’ll be compiling to PDF (pdf_book), let’s take a closer look at that section:

output:
  bookdown::pdf_book:
    toc: no
    template: null
    latex_engine: xelatex
    keep_tex: yes
    includes:
      in_header: templates/preamble.tex
      before_body: templates/doc_preface.tex

Importantly, we are pointing to the two other workhorses necessary for the PDF output: the .tex files. Note that these are adapted from people who know a lot more about LaTeX than I do; I changed very little, and mostly just moved stuff around. In their current form, they will output a document that adheres to the current Western thesis standards4.

  • The in_header line tells bookdown to incorporate everything in preamble.tex. If you’re familiar with LaTex, this is everything that comes before \begin{document}. This also contains important info like your name, department, thesis title, etc…

preamble.tex

  • The before_body line points to doc_preface.tex which contains all the pre-body text including the abstract, acknowledgements, table of contents, etc

doc_preface.tex

5.2 Ready, set, render!

To compile your dissertation for the first time, enter the following code in the console:

bookdown::render_book("index.Rmd", "bookdown::pdf_book")

Note that here we are specifying the pdf_book output format, but we don’t actually have to since it happens to be the first, and therefore default, output format specified in our YAML. We could just as successfully run bookdown::render_book("index.Rmd").

If all goes according to plan, you will see a smattering of new folders and files. Your shiny new book can be found in _book/_main.pdf

If things did not go according to plan, you will get an error and a request that you delete _main.Rmd before recompiling. _main.Rmd is a document that’s created in the process, but gets deleted when the final output has successfully compiled. It can often give you hints as to what went wrong (the lines where it got tripped up will be echoed in the error message). As instructed, you must delete it before you try to render again.

Other things to know

  • This is the “Merge-and-Knit” approach. See Yihui’s explanation of other rendering approaches here.
  • Yihui also recommends not rendering the full PDF that often, as it can be very time consuming when the output is large, and you run the risk of getting caught up with typesetting queries that are best left to the end. There is a way to preview individual chapters that Yihui has included in bookdown, but I will also discuss my own preview methods later on.
  • If you choose to use the LaTeX nomenclature package to handle abbreviations, you need to do some additional work to get the abbreviations to show up the first time. I recommend scrolling to this section in Lucy’s blog post
  • Chapter headers (Chapter 1, Chapter 2, etc) are inserted when you use a first level header, e.g. # Header 1. Subsections within a chapter are assigned based on the subheaders you use (e.g., ## Header 2, ### Header 3…)

5.3 Intermediary stages

I like to do a full rendering of my PDF anytime I make major changes, just to make sure everything still works so as to avoid major errors along the way.

In the interim, I have a couple of different methods for viewing my work. These are some suggestions:

  • Bookmark an .html version of your most recent version for quick and easy viewing: Every day, I compile a gitbook version of my dissertation. This outputs an HTML file that can be viewed in a web browser. I’ve saved this page to my Chrome bookmarks so I can easily glance at the most recent version whenever I want.

  • Keep a bookdown project of notes that can also be bookmarked and easily viewed: I also have another bookdown project that I update regularly called my dissertation “roadmap”, and which is also bookmarked for easy access. I use this “book” as a collection of notes to myself (mainly changes to my methodology, issues I’ve run into with compiling, etc…). I also used it to cut my teeth on while getting used to bookdown, before actually compiling the bones of my dissertation for the first time.

  • Knit individual chapters in isolation: You can knit individual .Rmd files to see how images show up, how the text looks, etc. I like to knit to HTML on a very regular basis because it’s a) fast and b) shows up immediately in my Viewer pane in RStudio. I also will occasionally knit individual chapters as Word documents to see how they will show up when I send them to my supervisor for edits (see below), and to keep track of things that aren’t playing nice with Word.

  • Use child documents to knit partial previews of the dissertation to send to your supervisor/committee: My supervisor does not need to see my entire dissertation document every time I add a section. It is much kinder and realistic to send individual chapters or sections to him. Furthermore, he likes to receive things in .docx format so he can used tracked changes to add suggestions. After much hemming and hawing, I have settled on a workflow for this that I am happy with, though it is by no means the best option for everyone. See the next Section 6.

  1. YAML (rhymes with camel): The frontmatter/metadata that tells R Markdown how to generate your document. Indentation and spacing are very important. Stands for “YAML Ain’t Markup Language” or, less meta, “Yet Another Multicolumn Layout.”↩

  2. The thesisdown package readme has a nice list of other templates that people have adapted for their universities if you’d like to compare other .tex input files.↩