Section A.1 Prerequisites
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.โ1โ
If you already have and like usingatom or SublimeText, those both also have pretext packages that do similar things.
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, typepython -Vto see the version of python you have installed. You might need to try
python3 -Vif 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 --helpand 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 calledpdf2svg
. 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 typinggit --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 "johndoe@example.com"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 ashttps://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...โ.