Section K.1 Software prerequisites
We begin with the programs you will want to have installed prior to using the PreTeXt-CLI. All software can be downloaded free of charge, and is relatively easy to install.
Subsection K.1.1 VSCode
VSCode is short for Visual Studio Code. This is a text editor developed by Microsoft; we recommend it not because it plays well with Windows (although it does), but because of the availability of the
pretext-tools add-on, which will let you run the PreTeXt-CLI without leaving the editor.To install, the editor, first download the installer from the VSCode website.
1
code.visualstudio.com
When running the installer, be sure that the “Add to PATH” option is selected:
You should now have VSCode installed on your system.
Subsection K.1.2 Python
One difficulty with using PreTeXt on Windows is the fact that Python is not core software, and there are many different ways to install install. The recommended method for installing Python is to get it directly from
python.org. Other Python installations, such as Anaconda, or even Miniconda, include a lot of extras that we don’t need.To install Python, simply download the installer from the Python website.
2
python.org
When you run the installer, be sure to check off the box to add Python to the Windows PATH during installation. This will ensure that Python commands can be run from the command line without needing to provide the path to the Python program.
Subsection K.1.3 Git for Windows
The next piece of software we need to install is Git for Windows. This will provide tools for allowing us to interact with textbook source on GitHub. More importantly, it provides us with the Git Bash terminal, which is what we will be running all of the commands for PreTeXt.
You can get Git for Windows at
gitforwindows.org.The installation process for Git for Windows can seem quite complicated, as there are a lot of options, and many of them are quite technical. You can safely choose the defaults throughout, unless there is a particular setting you’re familiar with that you wish to change. The only thing you might want to do is change the default editor. Since we have already installed VSCode, we can choose to use that instead of an editor like Emacs or Nano that you may be unfamiliar with.
Subsection K.1.4 Other software
A number of additional programs may be needed to assist in processing your book, depending on what elements your book contains.
- LaTeX
-
You will almost certainly need to be able to process LaTeX, either to produce the PDF version of your book, or to process LaTeX images for the HTML version of your book.There are two ways to install LaTeX on Windows: MikTeX, or TeXLive
3
miktex.org. Although TeXLive is the default LaTeX distribution for Linux and MacOS platforms, most Windows users find MikTeX easier to use, since it comes with package management software to assist with automatically installing needed LaTeX packages. One thing to keep in mind: with MikTeX, you must run an initial update from the MikTeX pacakage manager before it will work correctly.4
www.tug.org/texlive/windows.html - pdf2svg
-
If your book contains LaTeX images such as TikZ, the PreTeXt-CLI will process those images using whatever version of LaTeX you installed, and then it needs
pdf2svgto convert the output to SVG format for use in HTML.There is no Windows “installer” for thos program. Instead, it is available as a GitHub repository. The easiest way to get it onto your computer is to use the newly-installed Git Bash terminal. The first time you open Git Bash, your working directory might be the rootc:drive. Typepwdto find out what folder you’re in. It doesn’t matter where you installpdf2svg, as long as you’re aware of where it is. If you want to change to a different folder, you can do so using thecdcommand.An important note of caution: avoid using directories such asProgram Filesthat have spaces in the name. This can cause problems with some of the scripts used by the PreTeXt-CLI. For this example, we will choose to place the program in our own user directory. In Git Bash, typecd Users/Sean(where you will replace “Sean” with your own user name, as long as it doesn’t contain spaces).Next, go to the pdf2svg repository on GitHub. Click on the “Code” button, and then click on the clipboard icon to copy the URL, as shown below:5
github.com/jailos/pdf2svg-windows
Next, in Git Bash, typegit cloneand then right-click to paste the URL you copied, or use the keyboard shortcut Shift-Insert. Hit Enter.You will now have the necessary software downloaded to your computer. In my example, it is now available inC:\Users\Sean\pdf2svg-windows. To complete the installation, we need to add the program to the Windows environment variables. Hit the Windows key, and type “path”. Open the suggested program.As shown below, click on the “Environment Variables...” button, then click on the line beginning with “Path”, and click on the “Edit” button. You can then click on “Browse”, and find thepdf2svg-windowsfolder you just downloaded.You should now have a working installation ofpdf2svg. To confirm, typewhich pdf2svgin Git Bash. It should display the path to thepdf2svgprogram. (You may have to restart Git Bash first.)
- Sage
- If your book includes Sage components, such as
sageplot(but not Sage Cells), you will need to install Sage to process them. Sage is available atwww.sagemath.org. Click on the download button, and follow the instructions in the installer. - GitHub Deskop
- If you find it difficult to manage git from the command line, GitHub provides a graphical user interface for the Windows environment, called GitHub Desktop. This provides a point-and-click interface for synchronizing your local changes with GitHub.
6
desktop.github.com
