Prerequisites

Section A.1 Prerequisites

The book is written in PreTeXt, which takes some getting used to. Luckily, there are some recently developed tools that make the workflow with PreTeXt quite a bit easier.

In order to collaborate on the book, we will use git and in particular GitHub. More information about how we will use this software and website can be found in Section A.2; in Subsection A.1.2 we will describe the initial steps to get set up.

Subsection A.1.1 PreTeXt and Related Tools

You can think of PreTeXt as something between LaTeX and html. You write content in plain text xml files, with start and stop tags (similar to html), but describe the semantic structure of your document, including definitions, theorems, proofs, etc. like LaTeX. You can also include mathematical notation using LaTeX syntax (except that you use <m> tags instead of dollar signs to signify “math mode”).

When you first look at the source of this document, it might be intimidating for two reasons: first, it might be hard to read with all the angle brackets, and second, you might worry that having to type all that “markup” will take forever. But both of these concerns are addressed by using a modern text editor with support for PreTeXt.

I suggest using Visual Studio Code, which is free and multiplatform. I have written an extension package called PreTeXt-tools that provides a bunch of “snippets” to use. For example, you can type thm and press tab to expand the entire theorem environment, with your cursor in the right place to start typing. After you download VSCode, go to the extensions button and search for “pretext-tools” and click install.¹

If you already have and like usingatom or SublimeText, those both also have pretext packages that do similar things.

You will want to play around with other extensions as well. I use a spell checking program Spell right, a custom color theme (to make the markup easier to read), Auto Close Tag, LaTeX Workshop (which is useful if writing in LaTeX), XML Format, and XML Tools (I don't remember if these are all useful; there are lots to play with). You will also notice that there are some extensions for working with git and GitHub, which should make those parts easier.

Python and Processing PreTeXt.

After you have written something in PreTeXt, you will want to transform the plain text xml files into html or latex (and eventually pdf) documents.

The easiest way to get started with this is to first ensure you have a reasonably up-to-date Python instillation and then install the PreTeXt command line tool.

Yeah, we will need to use the command line. On a Mac, this is the program called “Terminal”. On windows, the “Command Prompt” (or “PowerShell”). Linux has a “Bash”. If you have downloaded VSCode, you should be able to hit Ctrl+` (or Cmd+` on Mac) to pull up a terminal right in the text editor. I recommend watching a tutorial or two on using the command line if you haven't done so before (you will likely want to change folders, for example).

Back to Python. You should check whether Python is installed already. On the command line, type

python -V

to see the version of python you have installed. You might need to try

python3 -V

if you don't see a Python 3.? show up the first time. We are looking for a version of Python 3.6 or later.

If you don't have Python installed, you can download it from python.org.

Once you have Python installed, you should be able to install Python packages using pip. Check that you have pip installed with

pip -V

(or maybe pip3 -V; some linux setups have both python 2 and python 3 installed, which is why you would need to keep adding 3). If you don't have it, or think you might want to upgrade, see the documentation on Installing Python Packages.

The Python package we want is called “pretextbook”. To install, type,

pip install pretextbook

(later you can upgrade with pip install --upgrade pretextbook). Did it work? Try typing

pretext --help

and you should get a help message describing what the pretext command line tool can do. If this doesn't work, please contact your instructor.

LaTeX and tools for images.

We will likely want to draw some graphs in the book. I'm going to do this with tikz, and that will require some additional processing. To generate these images, you will need to have LaTeX installed. Let me know if you need help setting this up.

You will also need a program called pdf2svg. For Windows, there are instructions for setting this up in the PreTeXt Guide. On Mac, there are package managers that will let you install it (please let me know how you do this when you figure it out).

Subsection A.1.2 Git and GitHub

You can test whether you have git installed by typing git --version on the command line. If you don't have it installed, follow the directions for your operating system in the git documentation. You will also want to set some global configurations, as described in the First-Time Git Setup. In particular, make sure you tell git who you are by entering the following in a terminal:

git config --global user.name "John Doe"
git config --global user.email "[email protected]"

You will also need an account on github.com. A free account is more than sufficient.

An important distinction: git is not the same as GitHub. The program “git” is software that runs on your computer. It helps you manage repositories (folders) by keeping track of changes you make. One of the features of this software is the ability to sync your repositories with remote versions of the repository. The website GitHub is a hosting site for git repositories. But they have added a bunch of additional features, like issue tracking and pull requests (we will see what that means later). So we are going to use both, but you only need git installed on your computer.

VSCode has extensions that work with both git and GitHub. I don't use these often, but you can probably use them so that you don't ever need to use git on the command line. The commands shared in this guide should translate reasonably well to the functions in the text editor.

Subsection A.1.3 Getting the Book

Now you need to get a copy of the repository on your computer. This is done by cloning the repository. This book is known on GitHub as https://github.com/oscarlevin/math795-fall20.git. You can clone the repository from inside VS Code by completing the following:

From inside VS Code, open the Command Pallet (CTRL+SHIFT+P, or the first item under the “View” menu) and start typing “Clone”
Select Git: Clone. Then copy the name of the repository (https://github.com/oscarlevin/math795-fall20.git) and hit Enter.
Select a location to store the math795-fall20 folder. Note, you should NOT put this in a dropbox or other synced folder.
You should get a notification asking if you want to open the repository. Later, you can right click on the folder and “Open in Code” or open VS Code and “Open Folder...”.