Skip to main content
\( \newcommand{\lt}{<} \newcommand{\gt}{>} \newcommand{\amp}{&} \)

AppendixDWindows Installation Notes

Dave Rosoff

This appendix explains the best known way to install the MathBook XML toolchain in a Windows environment, rather than a Unix-flavored operating system (such as Linux and Apple's OS X). It has been tested on Windows 7, 8, and 10. We assume that none of the listed tools or equivalents have been previously installed. That may complicate matters. This is especially true if you use Cygwin, or if you have already installed Python on your machine. MathBook XML compatibility with existing Python installations is addressed elsewhere in this document (<<python-mbx-compatibility>>).

If you have Windows 10, be sure to read about WSL in Appendix E, which could be a whole lot easier to setup and maintain.

SectionD.1Setup

In this section, we do some initial setup, establish notation, and issue warnings. Some of the steps in this process are dangerous. Typos could lead to an unstable system, or possibly even to unrecoverable system errors. Double-check everything.

SubsectionD.1.1Notation

Strings enclosed in <angle brackets> are variables whose values you should substitute in typed expressions. <username>, for example, should be replaced with your Windows username (e.g., mine is drosoff). Throughout this installation process it is very important to pay attention to the direction of slashes / and backslashes \.

SubsectionD.1.2Initial Windows setup

It is easier to see what is happening if your Windows file browser is not set up to hide file extensions from you. Disable the “hide file extensions” behavior before proceeding. In Windows 7/8, this can be done through the Control Panel. In Windows 10, there is a checkbox somewhere in the ribbon for it.

ListD.1.1
  • On Windows 7 or 8:

    1. Open the Start Menu and type “Control Panel”. Select the Control Panel entry from the popup list.

    2. Type “Folder Options” into the search box in the Control Panel window. Select Folder Options when it appears.

    3. Select the View tab.

    4. Uncheck the box for “Hide extensions for known file types”.

    5. Click OK until there are no more OKs to click.

  • On Windows 10:

    1. Open the Start Menu (icon shaped like a Window at the bottom left, typically). Select the File Explorer option, right above Settings, from the popup list.

    2. Click on this, and then select View from the “ribbon lists” of options along the top.

    3. After clicking this, on the right there should be a check box for “File Name Extensions”. Click this box; that should do it.

SubsectionD.1.3A word on path names

An appallingly large fraction of the difficulties of using GNU/Linux-based utilities with Windows come from the differences in formatting path names. Windows path names begin with a drive letter (usually “C”) and a colon. Like all path names, they describe a path in a rooted tree. The root directory (folder) in Windows is called \, a backslash. Note the direction carefully. Children of the root node are either subdirectories or files in the root directory (leaves). The path to my downloads folder is:

C:\Users\drosoff\Downloads\

The trailing backslash is often unnecessary, but it is an easy way to see immediately whether a path name refers to a file or to a directory. Windows path names are not case-sensitive.

Linux/Mac OS X path names are quite similar, but lack drive letters, start with an explicit reference to the root, use forward slashes, and are case-sensitive (more or less so, in Mac's case). A path to a typical Linux user's download folder might be

/home/typical.username/Downloads

Again, Linux pathnames are case-sensitive and Mac OS X pathnames are typically ‘case-preserving’. The Git Bash shell for Windows is an emulation of a Linux environment, and the utilities within it expect path names that follow Linux conventions. So we conform to this expectation as follows.

  1. Remove the colon, but keep the drive letter.

  2. All backslashes \ become slashes /.

  3. Add an initial slash preceding the drive letter.

The path name to my Windows download folder becomes

/c/users/drosoff/Downloads

Even though Git Bash is pretending to be a Linux shell, path names are still the underlying Windows path names, and therefore are not case sensitive. You can verify this using tab-completion.

Path names that begin with the drive letter (Windows) or the root / (Linux/Mac OS X) are called absolute path names. Their referents do not depend on the location from which the path name is invoked. Relative path names, on the other hand, begin in the so-called current working directory. A relative pathname might look something like this:

../../examples/sample-article/sample-article.xml

The symbol .. is a shortcut for the parent of the current directory. Thus, the relative path name above means from where we are, ascend two levels, then descend into the examples and sample-article subdirectories, and find the file sample-article.xml.

Path names that contain spaces are evil, and should be avoided in many cases. Unfortunately, all Windows default program installation locations contain at least one space (directory name “Program Files”). This does not appear to cause problems, except when installing ImageMagick (Section D.5). To be extra careful, you could always choose an installation location that is free of space characters.

SubsectionD.1.4Do I have 64-bit Windows?

Find out on Windows 7:

  1. Open the start menu and type “Computer”. Right-click the Computer item in the popup menu.

  2. Select Properties from the drop-down menu.

  3. Read in the right-hand side of the pane to find the “System” heading.

  4. From the “System type” entry, read whether you have a 32- or a 64-bit OS.

Now you are ready to begin installing the various pieces of the MathBook XML puzzle. The first one, xsltproc (Section D.2), is the most annoying. You might want to go get a snack or another cup of coffee.

SectionD.2Installing xsltproc

SubsectionD.2.1xsltproc binaries

This is the most annoying part of the installation. Obtain four zip archives from Igor Zlatkovic's FTP site that hosts the most recent Libxml binaries for Windows. At the time of this writing, the 64-bit binaries were considered experimental. I have had no trouble using the 32-bit binaries on my 64-bit Windows 7 system, so I suggest that all MBX users download the most recent 32-bit version of the following libraries:

ListD.2.1
  1. iconv (filename something like iconv-1.9.2.win32.zip)

  2. libxml2 (filename something like libxml2-2.7.8.win32.zip)

  3. libxslt (filename something like libxslt-1.1.26.win32.zip)

  4. zlib (filename something like zlib-1.2.5.win32.zip)

We only need a handful of files from these archives. So the simplest thing is to leave them in your Downloads folder and grab what we need. Create a new folder C:\xsltproc (it can be anywhere, as long as it's a new location). We'll call this location <xsltproc> in case you named your folder something different.

Extract the following files from the four zip archives you downloaded above into <xsltproc>:

ListD.2.2
  1. From iconv-*.win32.zip:

    1. iconv-*.win32\bin\iconv.dll

  2. From libxml2-*.win32.zip:

    1. libxml2-*.win32\bin\libxml2.dll

    2. libxml2-*.win32\bin\xmllint.exe

  3. From libxslt-*.win32.zip:

    1. libxslt-*.win32\bin\libexslt.dll

    2. libxslt-*.win32\bin\libxslt.dll

    3. libxslt-*.win32\bin\xsltproc.exe

  4. From zlib-*.win32.zip:

    1. zlib-*.win32\bin\zlib1.dll

SubsectionD.2.2Change PATH environment variable

Note: if you prefer not to meddle with this, it can be avoided. Now, we need to make sure your system can find these files when we need them.

ListD.2.3
  1. Open the Start menu and start typing “Edit the system environment variables”. Select this option when it becomes visible.

  2. Click the Environment Variables button near the bottom of the dialog.

  3. In the bottom part of the dialog labeled “System environment variables”, look for a variable named PATH. You may need to scroll.

    1. If you do not find one, create it using the New... button. Make sure to use all capital letters. (This really shouldn't happen. Make sure you are editing the system environment variables, not the user environment variables.)

    2. If you do find the PATH variable, select it and click the Edit... button.

  4. Regardless of which of steps 1 and 2 you followed, now you should see a dialog with two text fields. Your variable name should be PATH.

  5. If you created this variable, populate the second field with the full path name of <xsltproc>, the location where you put the seven files from Igor's zip archives. For me this looks like C:\xsltproc.

  6. If you are editing the PATH variable, place the cursor in the existing value and press the End key, so that the cursor moves to the back of the line. The PATH string is a ;-delimited list of full path names, so append the string <xsltproc>; (note the semicolon) to the existing value. If you named <xsltproc> as we suggested above, then the last part of your PATH variable is now C:\xsltproc;.

  7. Click OK to save changes.

Congratulations, you have successfully installed xsltproc.

Note that you have installed the xmllint utility as part of this procedure. This utility will allow some text editors to lint your MathBook XML files, that is, to automatically detect and highlight errors, and perhaps even to explain them.

SectionD.3Installing git

In this section we install the git version control system and some tools to interact with it, including a fairly full-featured emulation of the bash command line shell. I strongly recommend you use the Git Bash shell or another bash emulation, so that you can use Linux commands referenced elsewhere.

One feature in particular, pdfcrop, has not been made to work in the normal Windows cmd shell, although the rest of MathBook XML has. To generate images using the mbx script Section 8.3, you will need the Git Bash shell or something like it.

SubsectionD.3.1Steps to install git

ListD.3.1
  1. Visit the official git download page (download starts automatically) and obtain the latest binary for your system.

  2. Find the installer in your Download location and run it.

  3. Choose whatever location you like for the git installation folder. I recommend you use the default.

  4. At the “Adjusting your PATH environment” dialog, select either of the first two items. I recommend the second, “Add git executable to Windows PATH”. This will allow you to use git from within other Windows programs, such as Sublime Text or other text editors, which can be extremely convenient. If you are apprehensive about adding git to the Windows PATH, select the first option. I do not recommend the third option.

  5. Accept the default options for all the remaining prompts.

SubsectionD.3.2Changing the path with .bashrc

In Subsection D.2.2, we promised that you could avoid messing with the Windows environment variables. If you install something else later that wants to use xsltproc, then this might not be the best idea. But if you are only going to use it from within Git Bash, then this will work fine.

From the Git Bash command prompt, enter this line of text and hit Enter. Do not make any typos. You should substitute your value of <xsltproc> where indicated, but make sure to conform to the conventions at the end of Subsection D.1.3 regarding Windows path names in Git Bash. (I warned you this was going to be annoying.)

echo "export PATH=<xsltproc>:$PATH" >> ~/.bashrc
You may get a message from Git Bash the next time you run it about .bash_profile, which you may safely ignore.

Congratulations, you have successfully installed git.

SectionD.4Installing Anaconda

Anaconda is a well-regulated development environment for Python under Windows, and I recommend it for users who do not already have Python installed. The essential mbx script has recently been updated to support both Python 2 and Python 3. Therefore we make no recommendation about which Python version to choose.

If you already have a working Python installation, skip to Section D.5.

You have some choice with your Anaconda installation. It actually supports the installation of several independent Pythons side-by-side (since both 2.7 and 3.x are in active use, this is more reasonable than it seems). If you do not need Python for anything else or are simply a minimalist, Miniconda is also an option. Miniconda installs no packages, but these can be installed via the conda utility at the command line later.

  1. Download either Miniconda, Python 2.7, or Python 3.5 from the Anaconda download page.

  2. Run the installer and accept all the default suggestions.

Congratulations, you have successfully installed Python.

If you do not care about images, you can stop here. Much of the MBX functionality is already present. However, to use the mbx script to create SVG images from sources like PDF/PNG images, Sage, Asymptote, or TikZ, you need to install ImageMagick and Ghostscript using the directions in Section D.5 and Section D.6.

SectionD.5Installing ImageMagick

Visit the ImageMagick downloads page and grab a binary. If you have a 64-bit Windows installation (Subsection D.1.4), use the recommended version. If you have a 32-bit installation, find the version whose filename is obtained from that of the recommended version by substituting x86 for x64. For example, if the recommended version's filename is:

ImageMagick-7.0.1-6-Q16-x64-dll.exe

then a good choice for a 32-bit Windows would be

ImageMagick-7.0.1-6-Q16-x86-dll.exe
ListD.5.1
  1. Run the installer from your download location.

  2. Accept the license agreement.

  3. Choose a default installation location that has no spaces in its folder name. The default choice “Program Files” causes problems because of path name issues. I chose

    c:\ImageMagick-7.0.1-Q16\
    It matters because the ImageMagick utility convert is used by the mbx script to convert your images into different formats. The mbx script will have a lot of trouble with path names that contain spaces.

  4. When confronted with “Select additional tasks”, make sure that the boxes for “Add application directory to your system path” and “Install legacy utilities” are checked.

  5. If you like, carry out the procedure to verify your installation.

Congratulations, you have successfully installed ImageMagick.

SectionD.6Installing Ghostscript

Visit the Ghostscript download area and download the most current binary for either 64-bit or 32-bit Windows (Subsection D.1.4 ). Run the installer. You can accept almost all the default options. As with ImageMagick (Section D.5), it is probably best to choose an installation location whose path name is free of spaces, such as c:\gs. We refer to this installation location as <gs> below.

SubsectionD.6.1Change PATH environment variable

The pdfcrop utility needs to be told which Ghostscript command to use. We need to add the file gswin64c.exe to the Windows PATH. This is similar to what is done above, in Subsection D.2.2.

ListD.6.1
  1. Open the Start menu and start typing “Edit the system environment variables”. Select this option when it becomes visible.

  2. Click the Environment Variables button near the bottom of the dialog.

  3. In the bottom part of the dialog labeled “System environment variables”, look for a variable named PATH. You may need to scroll.

  4. If you do find the PATH variable, select it and click the Edit... button.

  5. You should see a dialog with two text fields. Your variable name should be PATH.

  6. Place the cursor in the existing value and press the End key, so that the cursor moves to the back of the line. The PATH string is a ;-delimited list of full path names, so append the string <gs>; (note the semicolon) to the existing value. If you named <gs> as we suggested above, then the last part of your PATH variable is now C:\gs;.

  7. Click OK to save changes.

Congratulations, you have successfully installed Ghostscript.

SectionD.7Installing pdf2svg

The installation procedure uses git. Open Git Bash and change to your root directory:

cd /c
Clone the repository into C:\pdf2svg:
git clone https://github.com/jalios/pdf2svg-windows.git pdf2svg

SubsectionD.7.1Change PATH environment variable

We need to add the pdf2svg program to the Windows PATH. This is similar to what is done above, in Subsection D.2.2 and Subsection D.6.1.

ListD.7.1
  1. Open the Start menu and start typing “Edit the system environment variables”. Select this option when it becomes visible.

  2. Click the Environment Variables button near the bottom of the dialog.

  3. In the bottom part of the dialog labeled “System environment variables”, look for a variable named PATH. You may need to scroll.

  4. If you do find the PATH variable, select it and click the Edit... button.

  5. You should see a dialog with two text fields. Your variable name should be PATH.

  6. Place the cursor in the existing value and press the End key, so that the cursor moves to the back of the line. The PATH string is a ;-delimited list of full path names, so append the string C:\pdf2svg\dist-64bits; or C:\pdf2svg\dist-64bits; (note the semicolon) to the existing value.

  7. Click OK to save changes.

Congratulations, you have successfully installed pdf2svg.

SectionD.8What's Missing

Development of a Windows-compatible mbx script (Chapter 8) is mostly complete. If you need help with mbx, contact Dave Rosoff. There are still a few use cases that haven't been tested, mostly those to do with Asymptote.

At present, it only seems to be possible to install Sage on Windows by way of the Windows Subsystem for Linux, available only in Windows 10.

If you find any problems or bugs, please let us know at the MathBook XML Support group in Google Groups, or email drosoff AT collegeofidaho DOT edu.