Software and GitHub account setup

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 [2], though we recommend avoiding performing the task described in Section E.2.2; see Step 5 below.)

You may perform most of the installations in any order, but should perform Step 5 after Step 2.

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 [2].

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.
1. Install Git by choosing the Windows option at https://git-scm.com/book/en/v2/Getting-Started-Installing-Git and selecting the default options.
  
  Why this installation? From the Introduction in [1]: “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 [1].
2. 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.
Installation and shortcut creation difficulty level: Easy.
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 xetex.exe and 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.
Install xsltproc.

Follow the instructions for installing xsltproc exactly 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.html and the discussion of the installation of xsltproc begins in the video at 3:31. We elaborate on some of the video instructions below.
- 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 [2].
- It is essential that you install the xsltproc files 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 c/users/username, where username is 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 xsltproc folder 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 [2].
Why this installation? xsltproc is 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.

Prev Top Next