Versions Compared

Old Version 7

changes.mady.by.user Alexander Jordan

Saved on

compared with

New Version 8

changes.mady.by.user Alexander Jordan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 easyare still experimental and I'm unable to help with how to use them. 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) and 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.

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

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

    • 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:
    Image Removed
    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:
    Image Removed
    You can use

    ls
    to list all the files in this folder:
    Image Removed
    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 folderThe following steps worked on 12/01/2016 on a fresh MacBook Pro running OS X El Capitan. It's possible that if your OS is different, you may run into (overcome-able) obstacles.

    1. From the Terminal prompt, install Homebrew by running:

      No Format
      /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

      You will be prompted for your Mac OS account's password.

       

    2. Istall git:

      No Format
      brew install git

    3. Make sure you are still in your user profile's root folder:

      No Format
      cd ~/
 

      That is a tilde character, not a hyphen.

    4. Clone the MathBook XML repository:

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

    5. Install the utility that converts pdf images to svg images:

      No Format
      brew install pdf2svg

    6. Install ImageMagick; among other things it provides the "convert" command which can convert pdf images to png images:

      No Format
      brew install imagemagick

    7. Install pip, the Python package manager:

      No Format
      sudo easy_install pip

    8. Install the Python requests package:

      No Format
      sudo pip install requests
    9. Install a full LaTeX distribution by visiting http://tug.org/mactex/. (This is for Mac OS X.)
      Download the .pkg there. It's a very big file, so you may want to download it using a wired internet connection as opposed to wifi.
      Once downloaded double click to open the installer and just go with all the default settings.
       

    10. (Optional, if you would like to be able to make gource videos animating your repository history) install gource:

      No Format
      brew install gource

    11. (Optional, if you would like to be able to save gource videos as mpeg videos) install ffmpeg:

      No Format
      brew install ffmpeg
    12. You may need to exit Terminal and re-enter before some of what you have just installed is available.

    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 (which you can be sure you are in by first running "cd /~"), clone

      this

      the repository using one of the following (or something like these):

      For the PCC Calculus Lab Manual:

      No Format
      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

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

    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

    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: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 withmkdir images
    But you can also create this folder from the OS Finder window.
  • Navigate to the mathbook folder. For me, after opening a Terminal window, that is just

    cd mathbook

    • 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.
    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
    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".
  • 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
    1.


      For ORCCA (Open Resources for Community College Algebra):

      No Format
      git clone https://github.com/PCCMathSAC/orcca

       
      For APEX Calculus: 

      No Format
      git clone https://github.com/PCCMathSAC/apex-mbx
    2. Navigate into the project's root folder. You can do this through Finder if you like rather than Terminal.
      In this folder, there might be a file called "Makefile.paths.original". Copy this file as "Makefile.paths". Open the file and edit it according to the instructions there. Possibly, there is also a "Makefile.paths.example" you could use to help understand what you are supposed to edit.

    Now what?

    At this point you should have all the software that you need to compile the various output formats for the project. And you should be able to edit the project's source files to make edits and contribute. The details of how to actually do any of these things vary from project to project, so it's not feasible to give comprehensive instructions here. If you make it this far, contact Alex Jordan to proceed.