MAA Workshop Notes

Subsection5.1The basics

First, let's have everyone check that they actually have the software necessary installed! Here are the main tools you need.

• A ‘text editor’ that allows you to make raw text files

• The xsltproc processor for processing your raw text .xml files

• The git revision control system (for now, just for downloading PTX)

• The PTX tools themselves, which you will see as mathbook in the directory you downloaded it to using git clone

There are many possibilities here. Does everyone want to get together in groups by platform to help each other out?

If you are unfamiliar with command line tools on Windows or Mac, you may wish to use a cloud solution, and I'd like to thank the generosity of SageMath, Inc. for providing internet access and space for our workshop for you to try PTX out in precisely that circumstance. Naturally, unless you are in a collaborative project, you'll eventually want local versions of everything sooner or later anyway! It is, remarkably for the fragmented tools world, quite possible – one of us even did it on Windows with no prior experience by following Dave Rosoff's excellent instructions.

Subsection5.2Make something compile

Your only next goal is to get something to compile. There are two sets of instructions.

• For everyone, see the PTX Quickstart page.

• For our workshop, I have some additional instructions at this markdown file.

Note that I did not say your goal was to actually author anything! Our next goal will be to have you (begin to) write your first document. Here is a guide for the perplexed.

• First, the only reason for the git clone command is to download the PTX software. This requires the internet, of course, so if you didn't have internet in the cloud project, it wouldn't work – and the same would be true on a local computer.

• Understanding the directory structure of files on Linux is not required, but helps a lot with only how to invoke xsltproc.

  Example5.1

  Everything must be done relative to where you are currently. Namely, the command in its most general form will look like this:

  way_to_get_xsltproc location_of_stylesheet_for_your_output_type location_of_your_file
  

  But this will look different different places. On Mac and Linux, the first part is just xsltproc; on Windows it may be something like xsltproc/xsltproc.exe or even more complex.

  The location of the style sheet will depend on whether you have just downloaded mathbook, if you cd (changed directory) to that folder, or whether you dove even deeper; the typical instructions for compiling one of the sample articles is to cd mathbook/examples/sample-article, so to find the stylesheets you would go back up two directories to the main mathbook directory, then find it – hence the two ../ in this command:

  xsltproc ../../xsl/mathbook-html.xsl sample-article.xml
  

  However, that assumed you were in the samples spot. If you are outside of the mathbook directory, then you still have to tell xsltproc where to find your source .xml file. Here is just one example, which assumes you are just in the same place you started when you did git clone and want LaTeX output for the workshop.xml document:

  xsltproc mathbook/xsl/mathbook-latex.xsl workshop.xml
  

• Finally, please never be afraid to ask for help, at any time. The PTX community is small but growing, and quite active!