AIM Textbook Workshop – Day 5

Today was the last day of the workshop.  In the morning we began by discussing options for print-on-demand services and other business considerations (e.g. ISBN numbers) that come with the manufacture of a physical instance of a book.  Then we had a panel of three former department chairs, leading a discussion about “professional credit” for authoring open-source texts.

For working groups in the morning, I led an exercise where everyone first authored a 2-page, 4-question examination in XML that they were to make up (with little advance discussion).  Then with some discussion of their choices and design, we turned to writing the XSL to convert their exams to LaTeX and from there to PDF.  We made a lot of progress in about an hour and I think everybody ended up with something they can expand on once they are home.

The afternoon had reports from many of the recent groups, and then a “look to the future” and/or “next steps” discussion.  That was followed by more opportunities to work with each other.

The week has been a great experience.  We began with a very diverse collection of book projects and a diverse collection of skills and experience.  It seems everybody learned a lot, has a better sense of where their projects are headed, and has gained new collaborators and colleagues.  I’d like to thank all the participants for everything they have contributed to make the week work so well, and my co-organizers for all the work to make it happen.

A Close Look at Rare Books

A Close Look at Rare Books

Co-Organizer David Farmer Explains Bad macros and Good Macros

Co-Organizer David Farmer Explains Bad Macros and Good Macros

Co-Organizer Kent Morrison Gets Happy Hour Started

Co-Organizer Kent Morrison Gets Happy Hour Started


AIM Textbook Workshop – Day 4

I did the last technical discussion in the morning, walking everybody through using the mbx script to generate images for the HTML version of the sample-book example.  We broke into small groups after break and I had a high-level technical discussion with Duanne Nykamp and Jim Fowler about representing mathematical expressions so that they could be employed meaningfully in interactive exercises.  Think Kahn Academy.

We are meeting in space that is part of Fry’s Electronics corporate headquarters (John Fry is a major sponsor of AIM).  The building also houses his collection of rare mathematics and science books.  So after lunch we had a tour hosted by AIM’s librarian, Ellen Heffelfinger.  We began with a copy of Euclid’s Elements from 1482 (printing press is c. 1454).  Then we moved on to books like Newton’s Principia Mathematica and a selection by other authors, such as, say, Galileo.  Simply incredible.  Photos tomorrow, most likely — too late tonight.

Afternoon began with an excellent discussion about licensing.  Perhaps one of the more valuable things we have done.

Bob Plantz, a retired computer science professor, living north of San Francisco, came down to visit us in the afternoon.  He’s writing a book about assembly language programming on the Raspberry Pi, using MathBook XML.  It was very nice of him to visit, and great for everybody to meet an Internet collaborator in the flesh.  A small group took Bob up to Palo Alto for dinner at the So Gong Dong Tofu House.    We capped off the day with a drive-by of Steve Job’s house.

Korean Dinner

Korean Dinner

AIM Textbook Workshop – Day 3

We lost Oscar Levin this morning – his wife went into labor four weeks early!  We wish his family the best,  Oscar was a huge help with participants getting started on Windows machines, and was the first to suggest to me structuring an example with both a statement and a solution.

Introductions on Day One

Introductions on Day One

Settling in to the routine.  The morning was a few announcements, followed by a nice presentation Tom Judson made about graphics.  There were general considerations, and some MBX-specific items, which were all presented clearly and thoroughly.  After break, Alex Jordan gave another nice presentation on incorporating WeBWorK problems into a book, and all the various permutations and variations on that theme (an OpenOregon-funded project Alex and I worked on last summer).  There were several impromptu rounds of applause for some of the techcnical achievements.  Robin Cruz and Lynda Danielson (University of Idaho) have the most “webwork-heavy” project and they seemed to like what they saw.

After lunch, David Farmer did the infamous two-round voting procedure for breakout sessions.  Not by design, but I ended up facilitating a group Matt Boelkins proposed to initiate the structure of a book AND use git in a group to accomplish this.  I had to think hard and quickly to design an effective and instructive experiment.

  1. Matt built a new repository on GitHub.
  2. Dave Rosoff cloned it locally.  Then he made a master file from the sample-book, pointing to seven new, empty chapter files, one for each person in the room.  He pushed these changes to GitHub, and then everybody cloned this two-commit repository.
  3. All seven wrote a mock MBX chapterlocally , and commited their changes on a branch of their local repository.  Now the fun began.  How to share the seven new chapters?
  4. Matt did a merge of his branch onto master.  Easy, since he was first.  He pushed to master on GitHub.
  5. Now everybody pulled Matt’s changes into master on their local copy.  Now everybody (but Matt) had their chapter in a commit branching one step behind master.
  6. So Greg Hartmann went next and rebased his chapter branch onto the tip of his master (no conflict since everybody was in different files) and then merged into master.  He pushed his chapter to GitHub and everybody (including Matt) pulled.  Now Matt and Greg were whole, but everybody else had their chapter in a commit branching two steps behind master.
  7. Just for conceptual purposes, I had Dave skip the rebase and merge his chapter branch into master, creating a new merge commit, and he pushed that all to GitHub.  Everybody pulled Dave’s chapter.  Michelle Manes was next, then maybe Volcker Ecke and Dimple C.

End goal was all seven chapters, available to process into HTML and LaTeX.  I saw Matt successfully build HTML of five chapters that were available at that point.

Git Help Session

Git Help Session

That consumed the afternoon.  For dinner a small group of us found an Ethiopian restaurant on San Carlos Avenue (the Lunch Box), that was so authentic that we were a bit of an oddity.  I almost (almost) felt like I was back in Africa.

Observation of the day:  Jen Nordstom’s “Introduction to Game Theory” text went up as got repository yesterday afternoon.  Today, if I speak “introductory textbook game theory liberal arts” to Google on my pocket computer, then Jen’s repository is the second result.  Amazing.

AIM Textbook Workshop – Day 2

First topic up today was Git and GitHub, as a way to contribute to an open source book project.  The main thrust of David Farmer’s presentation was to show how you could fork the official repository for project on GitHub, then clone it to local storage on your laptop.  Then you make edits on a branch, push them to your fork on GitHub, and then ask GitHub to send a “pull request” to the maintainers of the official repository.  As detailed in Chapter 4 of the new “Git for Authors.”

We  set up a practice repository with a real research mathematics article split into 27 files, each with some “bad LaTeX” introduced into it.  Watch the repository for progress locating the bad stuff and correcting it.

After break, I explained where participants could find the documentation on MathBooK XML, with the idea that they could experiment and decide if moving to XML source was right for their project.

The afternoon was a lot of independent work.  Mostly I helped Jen Nordstrom put her “Introduction to Game Theory” text into a git repository (LaTeX files), which David Farmer promptly converted to MathBook XML and sent back to Jen as a pull request.  We messily merged that (failed to push, though, so no link!), and Jen was able to produce a pretty-good HTML version of her text.  I think it is now time for her to leave the nest.

Oscar Levin and Dave Rosoff, along with several others, cracked the code and we have  xsltproc  running on Windows!  Yahoo!  That is a huge practical step forward.  Details later.

Wednesday morning:  Graphics (Tom Judson), WeBWorK (Alex Jordan).

AIM Textbook Workshop – Day 1

Great first day at the Open Textbooks Workshop at AIM.  Many people I have worked with, many people I have known only online, and many new people that it was great to meet for the first time.

After a warm welcome from the AIM staff and logistical announcements, we went through introductions.  Everybody was very thorough and it was very good to hear about their book projects and their teaching, in addition to their motivations and goals.  It took ninety minutes and was “totally worth it.”  But we were immediately ad-libbing the schedule.

After the morning break, until lunch, I showed as much as I could of the features of MathBook XML output.  There were lots of great questions and some discussion, so the informal atmosphere was established from the start.

For the afternoon everybody worked in SageMathCloud, so  we had a common computing  platform.  We cloned MathBook XML from GitHub, then processed the “minimal” example into a PDF and HTML.  It is a small fiddle to view your HTML files out of SageMathCloud, but everybody got it.  There were a few delighted smiles in evidence.

I dissected the XML source of the minimal example, which garnered some good questions and more discussion.  We then used the editor in SageMathCloud (a CodeMirror instance) so that everybody could author their own XML file.  We did the single sentence example in the Author’s Guide (Chapter 2) step-by-step and then everybody was turned loose to work at their own pace.  Some people started adding in math, and I saw that Ben Atchison constructed a table.  Duane Nykamp brought forward a bug (inconsistent headings of a section in an article, PDF vs. HTML.)

Tomorow is GitHub with David Farmer.  Tom Judson is blogging daily as well at:

AIM Textbook Workshop – Day 0

I’ll be spending the week at the American Institute of Mathematics, as co-organizer (with David Farmer and Kent Morrison), of a week-long workshop, Open textbooks in MathBook XML.

We’ll be working with MathBook XML, Git and GitHub, WeBWorK and a variety of other topics surrounding the authoring and production of open source textbooks in mathematics.

I’ll try to post daily on activities.  If I’m not too exhausted.

More Student Copy Editing

The flip side of student copy editing is that sometimes the response time by an open source author can be very rapid.

A couple weeks ago Hayden Harper asked a question in class about Exercise 21 from Chapter 19 of Tom Judson‘s Abstract Algebra: Theory and Applications. His confusion about the problem boiled down to the smallest element of a Boolean algebra being mistakenly typeset as the numeral zero “0” rather than an upper case letter “O.”

8:13 AM PDT I suggested Hayden send me an email about it. Yes, in class. Yes, now. Finally he could tell I was serious and used his phone to send me the details.


9:37 AM PDT Back in my office after class, I forwarded Hayden’s message to Judson.

11:04 AM PDT The git commit shows Tom made the change official less than 90 minutes later.

Noon PDT Back to my office after my second class, and I got an acknowledgment from Tom, “Fixed!,” which I forwarded to Hayden.

Try that with your commercial text!

Open Source Copy Editing

My students are excellent copy editors.  They scrutinize the material carefully, frequently asking themselves if the material makes sense.  So I pay my students when they report mistakes.  Which often happens the night before examinations.  Originally I paid $0.50, $1, $2, as my open source linear text evolved.  As mistakes got harder to find, I upped the ante on “mathematically significant” mistakes they found.  $5, $10, then in Spring 2014 it was $25.  I expected to pay off on about four that semester, it ended up being six.  The mistake can be very simple (like a missing subscript), but if it makes the mathematics wrong in any way it is “payable.”  The offer this semester is $50.


Rachel Chaiser is the first to find a qualifying $50 mistake.  She found a stray addition sign in the proof of Theorem PSPHS.  Just one character.  Thanks, Rachel.

I like to say that open source books can be better than commercial texts. One advantage is the ability to correct mistakes quickly and easily, and the interest of readers to give something back in the way of simple corrections when they see them. I had a very subtle error pointed out to me this summer by 45-year-old Italian, Marco Milletti, that had no doubt been present for many, many years.  Thanks, Marco.

Pennies a Day for SageMathCloud

7.4 cents per day to be exact.  That is what the new student course plan for SageMathCloud costs a student at $9 total for four months of members-only hosting, with network access, 1 GB of RAM and 3 GB of disk storage.  As an instructor you get all the advantages of assigning, collecting, marking, and returning assignments with the well-designed course interface.

This is an update of my detailed explanation of how to set up, and use, SageMathCloud to run a course that features computation.  If you have not read that, it would be the best place to start.  A few things have changed, and I have a few new comments, but the vast majority of that post is still applicable.    Skip below to the “Course Plan” section if you are just curious about how the $9 plan works from an instructor’s view.

The course functionality went very smoothly last term.  No one lost any work and generally everything came in on time.  Grading was very easy procedurally, and there is not much I could think of to make grading much more streamlined.  (But then, I have small classes and no TA’s to supervise.)

Abstract Algebra

My upper-division course in abstract algebra continues with regular Sage worksheet assignments from Judson’s open source textbook.  Last semester, I pushed out blank Sage worksheets for them to use for their submitted work, which had boilerplate instructions about the %html magic and exhortations for them to explain their work.  Two students decided they liked to submit Jupyter notebooks instead, which was fine with me.  They named them things like “GradeMe.ipynb”.  The point is, you can have students just make a new worksheet in the folder you push out and have them name it clearly (and with the default sort order by time, it is usually the last thing they have touched so at the top of the file list in their collected folder).

If you grade Jupyter notebooks, you’ll want to know Esc-A and Esc-B for new cell above or below, Esc-M for making a new cell into Markdown format, and then put some HTML for color and size of a div element onto your clipboard manager for quick pasting.

Last semester I strongly advised these students to purchase the $7/month Standard Plan for 3 or 4 months.  So they have done their part as early supporters of SMC.  I support SMC with a $49/month Premium Plan, which has more firepower than I need, though I am slowly becoming addicted to the upgrades.  With 16 members-only project upgrades, and as owner of the student’s course projects, and with a slightly smaller returning group, I was able to give each student a members-only upgrade for the semester (which I will claw back in May).

This is one of the things I really like about the upgrades and quotas – you can distribute them temporarily to collaborators: students, TA’s, research students, and colleagues anywhere.

Linear Algebra

My linear algebra students are mostly new to me.  They will be learning lots of Sage, they will be using a very limited subset of Sage during exams via the Sage Cell Server on their laptops, and they have fourteen proofs to write, and re-write, in LaTeX until they are rock solid.

I have about twenty Sage worksheets I use as demonstrations in class.  The first one was about constructing matrices and getting back reduced row-echelon form, which was a tool they could use on their first exam (two days ago), though they had to row-reduce one simple matrix “by-hand.”  The second one illustrated the dichotomy of linear systems with nonsingular versus singular coefficient matrices.  I put these in a single folder which I push out as an assignment.  Better, as suggested by SMC founder William Stein, is to use a separate folder for each worksheet.  That’ll minimize the chance that an update will overwrite student work.  This has not been a problem yet with my students, as they seem to understand that they need to make copies if they want to experiment.

Feedback from my students years ago suggests they don’t like to see you just step through a canned worksheet.  So I manufacture some things carefully in advance (like singular matrices) and create other things randomly (either at the keboard, or with Billy Wonderley’s random matrix commands in Sage).  I enter many of the commands I need live in class, so they can see me interacting with the system, and I can respond to their suggestions and questions.  So I make an “-inclass” version in advance, do my work there and save it at the end of class.  So the students get a virgin version of the worksheet that is incomplete, and a transcript of the class session.

For their proof-writing, the LaTeX editing and compilation is excellent, and I’ve used this as the rationale for required them to sign up for the course plan.  I spent about 10 minutes each of the first four class days, building up a demo/scratch LaTeX document with most of the basic features I thought they would need.  So I pushed out in their assignment a progression: DayOne.tex, DayTwo.tex, DayThree.tex, DayFour.tex.  Be sure to teach them about “commenting out” lines to locate compilation problems.

Before their first proofs were due, I had them make a test document, where the only requirement was that it had some math.  Of course, they were very creative with such loose guidelines.  I wanted them to get the result out as a PDF, saved locally, and emailed to me.  They submit their proofs on paper, since I have an elaborate system for the rewrites which I have failed at organizing electronically once already.  I’ve had trouble in the past with students who could not download and print a PDF before the first due date, so I get that out of the way with this mock exercise.

I had thought to hold “LaTeX Office Hours” the evening before their first LaTeX’ed proofs were due.  Timing was wrong, but I could conceivably have been at home after dinner, and as owner of their projects I could pop in and edit their LaTeX in SMC over the network, while they watched and let them also edit simultaneously.  Turned out fine, all their LaTeX looked quite good and only one student had a real question.

Course Plan

Make a course (see my previous post for details).  One update: if you know your student’s email addresses in advance, you can set up all their projects in advance by adding them with a single comma-separated list of addresses.  So as I suggested before, require your students to use their canonical school address when they make an account, and strongly suggest they use some variant of their real name, since that is what you will see.  If you add a student late by name, you will not see their email address in your list, so you may want to routinely use email as the identifier.

Now in your course “Settings”, find the first box, “Require students to upgrade (students pay)”.  Then set a date by which they must pay.  Be sure to customize the email invitation (off to the right) – I missed it the first time.  Done.  It is that easy.

I set the end of the trial period to be our “Last Day to Drop Without Record” day, which is about two weeks in to the semester.  60% have paid already.  I believe it is very clear in the student view how much time is left, and I’ll give them one in-class reminder tomorrow.

The setup is really flexible.  David Roe asked on the sage-cloud list:   What happens for students who don’t pay the $9?  Will they still be able to access their projects with a free “membership”?

William Stein replied:  No.  However:

  1. They could of course copy the files out to another project.
  2. They do get full access again (for free) when the course is over.
  3. You can set a start time at any point in the future (the default is one week).
  4. As the instructor, you can change the start time or remove the students-must-pay restriction instantly at any time with a click.  This takes effect immediately.

Maybe your school does not allow you to require extra fees of students.  There is an option for “Upgrade all student projects (you pay)”, which did not exist when I set up my Abstract Algebra course, so I do not yet have any experience with it, but it should be straightforward.