Introduction

Welcome

Welcome to the gaelsdown guide! This document is intended to get you up and running with writing your thesis in R markdown so that it can be published in a variety of formats, most importantly a .pdf with formatting specifications in the TeX language.

In this introduction chapter, I’ll go through the benefits of adopting gaelsdown into your writing process and what to expect, then explain the basics of how you get from a R markdown to a formatted pdf. Then, in the first chapter of the guide, I’ll provide you with all the basic tools to put together a document with formatting, figures and tables, and a structure appropriate to your thesis. In the second chapter, I’ll get into some of the more advanced methods for figures and tables, specifying formatting inline, and more. Finally, in the third chapter, I’ll go over some common issues and how you can address them, as well as providing more resources and approaches for troubleshooting.

Motivation

The purpose of gaelsdown is to enable you to write your thesis in R markdown so that you can focus on the content of your thesis. With R markdown, you can insert code for figures, tables, and references at ease, then transform the markdown file into a finished, formatted document that meets the specifications provided by the School of Graduate Studies. This is a departure from what may be a more familiar approach of using R to generate tables and figures separately, then inserting those into a “What-You-See-Is-What-You-Get” (WYSIWYG) editor like Microsoft Word.

There’s a number of advantages to this approach over using a WYSIWYG editor, including:

  • Your R code and writing are streamlined into one document, so that changes to figures and tables are automatically integrated whenever you knit your document, and the bibliography and table of contents are automatically generated.
  • R markdown is a much more lightweight format, which reduces the load on your computer significantly if your thesis has hundreds of pages and includes many figures.
  • The files making up your thesis are in plain text formats that can be easily transferred between platforms and require only free, open source software.
  • By using  to generate your document, you have access to a wide range of packages to support different types of mathematical and scientific formulas and a professional-quality typesetting engine.
  • Many journals make .tex templates available for authors, which can help with submission. There are also several options for converting from a LaTeX document to a Word-compatible format.
  • If you’re writing a thesis for Queen’s University, the formatting of the pdf output already conforms to the specifications that the school has published. If you’re writing for another school, or if you’d like to change some of the formatting, changes can be made in one place that apply to the whole document.

However, there are some potential challenges with writing your thesis in R markdown, especially if this is a new approach for you. This guide will help with avoiding or anticipating some of these challenges, but be aware of the following:

  • Introducing formatting changes into a LaTeX document is a different process than in a WYSIWYG editor, and involves a bit of a learning curve. However, by using a template such as gaelsdown, you can avoid much of the LaTeX editing and focus on the content of your thesis.
  • gaelsdown relies on a few different programs when it knits together your document, which means there’s a few different steps at which an error can be introduced. I’ll explain what these steps are, and tips for addressing any issues encountered at each step.

Structure

To understand how gaelsdown and similar template packages work, you need to understand the different software involved:

  • knitr converts your R markdown file (.Rmd) into a markdown file (.md). The different between a R markdown file is that it includes R code chunks that need to be rendered as images for them to be markdown compatible.
  • pandoc is included with your RStudio install and is capable of converting between a large number of different text formats, including markdown, Word (.docx), web browser compatible (.html), and LaTeX (.tex).
  • LaTeX renders a typeset format such as PDF from .tex files—if you knit into another format such as gitbook or Word, LaTeX will not have been involved.

Here’s a visualization of how it all flows together:

If you knitted this document locally from the gaelsdown package and watched the console carefully, then you’ve already seen all these steps in action! You can run the knit again if you want to review it.

Acknowledgements

The preface pretty much says it all.

Second paragraph of abstract starts here.