Chapter 2 Software and GitHub account setup
Here we provide a list of the steps you will need to take to get PTX up and running on your local Windows machine. (You can find more extensive documentation for this in Sections E.1–E.3 in Dave Rosoff’s invaluable Windows Installation Notes in , though we recommend avoiding performing the task described in Section E.2.2; see Step 5 below.)
Install a text editor.If you don’t already have one installed that you like to use, you will need to install a text editor that will produce “unformatted” text.If you don’t know what that means, or don’t already have such an editor that you like, we recommend installing Sublime Text, which you can download at
https://www.sublimetext.com/. (You can use the trial version for free indefinitely, but will get regular pop-ups asking you to register; as of summer 2017, registration cost $70.)For more extensive information about text editors you may use with PTX, see Appendix B in .Why this installation? You will write your PTX source documents using this editor.Installation difficulty level: Easy.
Install Git and create a shortcut to the Git Bash shell.
Installation and shortcut creation difficulty level: Easy.
Install Git by choosing the Windows option at
https://git-scm.com/book/en/v2/Getting-Started-Installing-Gitand selecting the default options.Why this installation? From the Introduction in : “Git \(\ldots\) is a revision control system. What’s that? It is a tool to record changes to software, a tool to experiment with changes to software, and a tool to collaborate creating software.”For more details on why you’ll be using Git (and how to use it!), see .
Create a shortcut to the file
git-bash.exe.Why this shortcut creation? You will perform all of your compilations in the Git Bash shell, which is installed when you install Git. You don’t need to know what it is, exactly, other than that it is a command-line interface in which you’ll enter your commands. If you’ve used Unix or Linux, you’re in your wheelhouse in the Git Bash shell. If you haven’t, don’t worry; we’ll cover the basics of what you need to know.
Sign up for a GitHub account at
https://github.com.Why sign up for this account? GitHub is a code hosting platform. We will later elaborate on how we will use GitHub.Sign-up difficulty level: Easy.
If you plan to create PDFs from your PTX files, you will need to have a LaTeX compiler installed. (If you only plan to create HTML files, you may skip this step.)If you don’t already have one, one option is MiKTeX, which you can download from
https://miktex.org/howto/install-miktex. Simply choose the default options when installing, as long as by default it installs into a folder whose path name (e.g.,
C:/Users/username/AppData/Local/Programs/MiKTeX/) contains no spaces. (Spaces in path names can cause problems, and should be avoided as much as possible.) If the default path name contains spaces, change the installation location to one that doesn’t contain spaces.If you choose another LaTeX compiler, make sure it includes the executable files
pdflatex.exe, and again, make sure to install it in a location that avoids spaces in its path name.Why this installation? We can compile our PTX files to LaTeX files using
xsltproc(see Step 5), but we must then use a LaTeX compiler to compile the LaTeX files to PDFs.Installation difficulty level: Easy, other than ensuring installation paths don’t contain spaces.
xsltproc.Follow the instructions for installing
xsltprocexactly as described in the Karl-Dieter Crisman’s Windows Getting Started video found at
http://mathbook.pugetsound.edu/documentation.html#getting-started-videos. The installation files are at
https://www.zlatkovic.com/libxml.en.htmland the discussion of the installation of
xsltprocbegins in the video at 3:31. We elaborate on some of the video instructions below.
Why this installation?
- A description of the exact files you will need to download from the website are found in Lists E.2.1 and E.2.2 in Appendix E of .
It is essential that you install the
xsltprocfiles in your default Git Bash directory in order for you to avoid making adjustments to later commands.To find what that directory is, open the Git Bash shell using the shortcut on your desktop, and enter
pwd. This will likely yield
usernameis the profile under which you’re logged into your Windows machine. In any case, this is your default Git Bash directory. You will need to move all the files you extract, as per the video instructions, into this directory.
- Do not move the
xsltprocfolder or its contents from their initial locations, and do not change the PATH environment variable name, despite this option being described in E.2.2 in .
xsltprocis a command line tool for applying XSLT stylesheets to XML documents. You don’t need to worry about what this means, but you do need to have the tool installed.Installation difficulty level: Moderate. (Potentially-difficult-to-hair-pulling if you try to change the PATH variable name.) Carefully follow the video instructions.