Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

MBX is the mechanism used to create the PCC calculus lab manual and other OER math books. This guide will get you started if you want to contribute on one of these projects.

This guide is for anyone who feels like a complete newcomer to projects like this. If you already know about things like git, then you should consider visiting the MBX homepage instead.

Until further notice, this guide assumes that you are working on a Mac. If you have a Linux machine, it is probably easy for you to work out the corresponding instructions. If you use Windows, the appropriate tools have not yet been developed that would make this easy. For Windows users, for now, if you really want to work on one of these projects, you should find a Mac that you can use.

We'll do almost everything from the Terminal:

Installing MathBook XML (MBX) Software Dependencies

MBX and MBX-based projects are not complicated things to install, but they rely on a fair amount of other software that we need first.

  1. Do you have Xcode installed? You can tell by opening your Terminal, and typing

    gcc


    If you get a message indicating you don't have Xcode, you need to install it.  This can be frustrating, because Apple updates the version of Xcode frequently and makes it only work for the most recent Mac OS. This will possibly be the most frustrating stage of this whole setup. You may have to do some internet sleuthing to find which version of Xcode is needed for your OS, and then further sleuthing to actually find that version, because the App store only offers the most recent version.
  2. Do you have homebrew installed? homebrew is an application for making it easier to install software on a Mac. Now that you have Xcode, you can install homebrew, which will make installation of subsequent software easy. Go to http://brew.sh/ and follow the instructions there.
  3. Install git. git is the version control management software that we need to manage all of the changes that happen with a project. It is also needed to get MBX itself. To install git, in the Terminal, enter

    brew install git

  4. Make sure that you have xsltproc installed. You probably do. You can check by executing

    xsltproc -h

    in the Terminal to see. (The "-h" just asks for the help menu for this utility.) If you somehow do not have xsltproc, you need to research online how to install it.

  5. You will need a LaTeX distribution. You won't need to know a ton of LaTeX to work on an MBX project. You will only need LaTeX math commands for your math content. For all of the other stuff LaTeX does with producing pdfs, you will be removed from that. MBX will be making use of LaTeX, not you. To see if you have what we need, execute

    xelatex --help

    from the Terminal. If the command is recognized, then you have XeLaTeX, which is what MBX uses. It's possible that you don't have all of the LaTeX packages that MBX will want, but you can address that later.

    If you do not have XeLaTeX, then you need to install a LaTeX distribution. Follow these steps to install it. Whenever given a choice, choose a full installation, which will give you LaTeX packages which may come in handy later. This installation may take a long time, on the order of an hour.

Cloning MBX

Now you begin using git. git is a type of software known as version control software. It allows many people to simultaneously work on the same software project. MBX itself is a software project that is under continual development, so you will use git to get MBX.

When you open your Terminal, you are probably in your user folder. For instance, this is what I see when I open Terminal:

The "alexjordan" is my user profile for the Mac I work on. I'm in the same place I am in when I use Finder:

You can use

ls
to list all the files in this folder:

Anyway, now you need to get MBX. You can see in my folder above that I have a mathbook folder. You will now simultaneously create such a folder and download MBX by executing:

git clone https://github.com/rbeezer/mathbook

Run ls again to see that you now have the mathbook folder.

Clone the MBX project that you wish to work on

These steps assume that you are going to work on the PCC calculus lab manual. If you wish to work on some other MBX-based project, then you will need to modify some things accordingly.

  1. The "master" PCC calculus lab manual repository is located at https://github.com/Alex-Jordan/Calculus-Lab-Manual. From the Terminal, still in your main user profile folder, clone this repository using:

    git clone https://github.com/Alex-Jordan/Calculus-Lab-Manual


    This should create a folder called Calculus-Lab-Manual and fill it with a local copy of the repository. As you read further, the abbreviation clm stands for Calculus Lab Manual.
  2. In this folder, there is probably an xsl folder. The files in this folder need to know where you have put your mathbook folder. For each of clm-html.xsl and clm-latex.xsl, open the file with a text editor and edit the line

    <xsl:import href="/Users/alexjordan/mathbook/xsl/mathbook-html.xsl" />

    <xsl:import href="/Users/alexjordan/mathbook/xsl/mathbook-latex.xsl" />

    So that the path is appropriate for your system. Most likely you just need to change "alexjordan" to your user profile folder name.

Check that you can create the print version

  1. In the Terminal, navigate to the src folder of the project's repository. Use cd for "change directory". For me, if I have just opened a Terminal window, I would use:

    cd Calculus-Lab-Manual/src
  2. Now you will tell the xsltproc application to apply the appropriate .xsl templates to the appropriate .xml files to generate a .tex file (which will later be turned into a .pdf). In the Terminal:

    xsltproc --xinclude ../xsl/clm-latex.xsl clm.xml

    The file clm.xml file is the "parent" file for the whole CLM project. Each chapter and section is stored in its own file, but this one file controls them all. The --xinclude switch is telling xsltproc that it will need to descend into those chapter and section files. The path ../xsl/clm-latex.xsl translates as "back up one folder, then into the xsl folder, then get clm-latex.xsl".

    Now if you list the files in your src folder, you should see some with .tex extensions, including clm.tex.

  3. Next you process this .tex file into a .pdf with

    xelatex clm.xml

    Hopefully there are no problems with compilation. However this may be the stage where some requisite LaTeX packages are missing from your distribution. If you have a compilation error, we need to investigate its specifics and work from there.

    You need to run the above command a second time. The first time, the locations of cross-references and internal links were compiled into a .aux file. The second time, xelatex will be able to use that .aux file to write the internal links into the .pdf appropriately.

    Now you should have clm.pdf, which you can open in a PDF reader. Congratulations! You have successfully compiled the source of an MBX project into a .pdf.

Check that you can create the HTML version

  1. Before we actually create the HMTL version, we need to separately create all of the image files. MBX comes with a script whose name is mbx that does this work. The mbx script is a little finicky about how it is used at present, so you need to do the following pretty much exactly:
    1. Navigate to the src folder of the project, and make sure there is an images folder. If not, create one. If you are in the Terminal, you do that with

      mkdir images

      But you can also create this folder from the OS Finder window.
    2. Navigate to the mathbook folder. For me, after opening a Terminal window, that is just

      cd mathbook

    3. Run this:

      ./script/mbx -c latex-image -f svg -d /Users/alexjordan/Calculus-Lab-Manual/src/images /Users/alexjordan/Calculus-Lab-Manual/src/clm.xml

      The translation is that you are executing mbx, asking it to find all latex-image components of the source files, convert them into svg formats, and put the results in the folder specified after -d. And you are doing all this to the file that is the last argument of this command.

      This will take a while to complete if you are working with the PCC calculus lab manual. Now that images folder will be filled with .svg images.

      If you are not working on the PCC calculus lab manual, there may be other components to extract besides latex-image components.

    4. In the Terminal, navigate to the src folder of the project's repository. Use cd for "change directory". For me, if I have just opened a Terminal window, I would use:

      cd Calculus-Lab-Manual/src

    5. Now you will tell the xsltproc application to apply the appropriate .xsl templates to the appropriate .xml files to generate .html files. In the Terminal:

      xsltproc --xinclude ../xsl/clm-html.xsl clm.xml

      The file clm.xml file is the "parent" file for the whole CLM project. Each chapter and section is stored in its own file, but this one file controls them all. The --xinclude switch is telling xsltproc that it will need to descend into those chapter and section files. The path ../xsl/clm-html.xsl translates as "back up one folder, then into the xsl folder, then get clm-html.xsl".

    6. You should be able to open clm.html now, and voila.

Editing source files

Within the project's src folder, you can edit the various .xml files that correspond to sections of the book. You can repeat the use of xsltproc as described above to see the changes in the output modes (PDF and HTML). When you have changes that you want to push back up to the "master" repository, then you need to use git appropriately. At some later point I will add tutorial steps for doing that.

  • No labels