Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Section L.1 Setup

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.

Subsection L.1.1 Notation

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 \.

Subsection L.1.2 Initial 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.
List L.1.1. Initial Windows Setup
  • 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.

Subsection L.1.3 A 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 L.5). To be extra careful, you could always choose an installation location that is free of space characters.

Subsection L.1.4 Do 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 PreTeXt puzzle. The first one, xsltproc (Section L.2), is the most annoying. You might want to go get a snack or another cup of coffee.
You have attempted of activities on this page.
PrevTopNext