Installing the CLI

Section K.2 Installing the CLI

You now have all the necessary software installed. Next, we need to set up Git Bash, and install the PreTeXt-CLI.

Subsection K.2.1 Setting up Git Bash

One change that you will want to make right away is setting the default working directory for Git Bash. In your home folder (C:\Users\Sean in our example), look for a file called .bashrc. If it doesn’t already exist, open Git Bash, navigate to this folder, and type touch .bashrc to create the file. Open the file (it is a plain text file), and add the line cd C:/Users/Sean, where you should replace the directory with the one you want to use.

Next, we need to set up SSH authentication, for more efficient communication with GitHub. We assume that you already have a GitHub account; it not, you should create one at github.com. There are existing instructions available online at docs.github.com

docs.github.com/en/authentication/connecting-to-github-with-ssh

. To begin with, please follow the instructions provided there for generating an SSH key using Git Bash, and adding it to GitHub.

There is one aspect of the instructions that is not quite correct. When you get to the step for adding the ssh key to the ssh agent

docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

, the instructions will tell you to add your SSH key to the SSH agent using a relative path, with a line such as ssh-add ~/.ssh/id_ed25519. You must use a full path here. Instead, type ssh-add /c/Users/Sean/.ssh/id_ed25519, where as usual you should replace Users/Sean with your own directory.

There is one more step you will want to complete. The ssh-agent program will not start automatically when you open Git Bash. To change this, we follow the instructions provided at gist.github.com/bsara/5c4d90db3016814a3d2fe38d314f9c23.

In the file /c/Users/Sean/.ssh, open the config file (or create it using the touch command in Git Bash if it doesn’t already exist), and add the following lines:
```
Host github.com
 Hostname github.com
 IdentityFile ~/.ssh/id_rsa
```
Note that the second and third lines are indented by one space. Note also that this assumes an RSA key, but you may have chosen a different encryption method. You may, for example, want to replace id_rsa with id_ed25519.
In the file /c/Users/Sean/.bash_profile, (again, create it if it does not already exist) add the following lines:
```
test -f ~/.profile && . ~/.profile
test -f ~/.bashrc && . ~/.bashrc
```

In the file /c/Users/Sean/.ssh, we need to add the following script, which will automatically start the ssh-agent.

# Start SSH Agent
#----------------------------

SSH_ENV="$HOME/.ssh/environment"

function run_ssh_env {
  . "${SSH_ENV}" > /dev/null
}

function start_ssh_agent {
  echo "Initializing new SSH agent..."
  ssh-agent | sed 's/^echo/#echo/' > "${SSH_ENV}"
  echo "succeeded"
  chmod 600 "${SSH_ENV}"

  run_ssh_env;

  ssh-add ~/.ssh/id_rsa;
}

if [ -f "${SSH_ENV}" ]; then
  run_ssh_env;
  ps -ef | grep ${SSH_AGENT_PID} | grep ssh-agent$ > /dev/null || {
    start_ssh_agent;
  }
else
  start_ssh_agent;
fi

You should now be set up to work with GitHub on your Windows machine. When you clone a GitHub repository containing a PreTeXt book, be sure to choose the SSH option rather than HTML.

Subsection K.2.2 Installing the CLI

Finally, we are ready to install the PreTeXt-CLI. This is perhaps the easiest step of the whole process. From the Git Bash terminal, first type which python to confirm that Python has been successfully added to the PATH. You should see the path to your Python program if things are working correctly. If you don’t, you may need to reinstall Python, or you can manually add it.

To install the CLI, simply type pip install pretext.

Congratulations! You are now ready to start using PreTeXt on your Windows machine. If you did not do so previously, there is one additional step you may want to take. In VSCode, go to File, then Preferences, then Extentions in the menu, or type Ctrl-Shift-X. In the search bar that comes up, type “pretext-tools”, and install the package that comes up. This will equip VSCode with syntax highlighting for .ptx files, as well as some automatic tag completion. (For example, typing thm and then the Tab key will automatically insert the XML markup for a theorem.)

Additionally, from the command palette, (View, then Command Palette in the menu, or Ctrl-Shift-P) if you type “pretext”, you will see some built-in options for building your book using the CLI.

Prev Top Next