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

Summer Progress on MathBook XML

I’ve made a lot of progress this summer on the XML application I have been developing. A better way to describe what I am building is a practical way for authors to create reports, articles and books with the structure explicitly defined, and with no presentation assumed. This will allow for faithful conversions to a variety of formats, and possibly with a variety of sensible options for presentation.

I have been most productive while writing such documents at the same time as I have been developing the application. Here is an example. I have submitted a short note to the American Mathematical Monthly. Authored with MathBook XML, it has been rendered as both a PDF and as a web page.

For the moment, I am trying to have the HTML rendering mimic whatever default rendering you would get from default LaTeX. But you will notice that the HTML version uses knowls for citations. As the HTML rendering evolves, expect it to take even greater advantage of the capabilities of browsers.

I have made a lot of progess with cross-references, including automatic numbering of displayed equations with MathJax. There is minimal support for bibliographic records. Figures and images are supported. A unified approach to tables will have to wait a bit. The CSS for the HTML is functional, but has lots more potential, especially for internationalization. Next I am going to tackle a book-length project that has lots of Sage code (so will make a doctesting framework).

An XML Application for Mathematics

Some high-level thoughts about a MathBook XML application. I am building an XML vocabulary which I hope will make possible

  • relatively painless authoring in XML for for mathematician-authors
  • capturing the full structure of scholarly documenst about mathematics
  • providing a wide variety of output formats accurately reflecting the content

To do this, I plan to

  • keep the number of tags and options to a minimum
  • resist too much customization, and resist customizing too much of the presentation
  • use simple processing tools, such as xsltproc on XSLT 1.0 features

Specifics and progress will be reported and updated on a project page at the Sage wiki. Priorities for new features will be based on requests. I’ll blog here on less technical aspects of the project.

The Case for an XML Application

This is the first of two introductory posts about my project supported by my Shuttleworth Flash Grant.  Rationale and motivation here, vague/concrete plan next.

Mathematics or not, I am convinced of the value of capturing scholarly documents in a structured form.  If you wish to have a variety of outputs for your writing, such as print, PDF, HTML web pages, and e-books, then it is a must.

Consider two very different scenarios.  First, when you place a bold typeface to a word, what do you really mean?  Is it emphasis, or perhaps a defined term?  Especially in an electronic medium (see output formats in the previous paragraph), you might wish to handle the two situations differently.  The emphasis could be bold in print, or colored red in an electronic version.  The defined term might be a hyperlink or pop-up window or knowl in the electronic version.  You might begin to see that authoring in a “word processor” is the exact opposite of what I am advocating.

Second, suppose you write in LaTeX. How do you know a subsubsection has ended?  Only when you encounter the start of another subsubsection, or the start of a new subsection, or the start of a new section, or the start of the chapter exercises, or the start of a new chapter, or the start of a new part (a major subdivision of a book), or the end of the book.  It can be a nightmare to process all these conditions in an automated way (see output formats in the previous paragraph), when LaTeX does not require a marker for the end of subdivisions like this.  Many people like to say LaTeX separates structure from presentation, but you can very quickly see this is a false promise, and is routinely violated by authors.

XML (eXtensible Markup Language) is an extremely simple language for describing the structure of text.  It is hierarchical (tree-like structure), and a begin is always accompanied by an end, like any structured programming language.  The vocabulary (“elements” and “attributes”) can be anything you like.  The output can be any format.  For example, you can create LaTeX as output (and then use standard programs to convert to PDF).  The power comes through the transformation language XSL (eXtensible Stylesheet Language) which is often called XSLT (T=Transform).  This is not an easy language to understand or learn.  But an author need only write with an accepted vocabulary and let an existing transform do the conversion.  The hard technical details of the output language can be captured in the transform.  A set of elements, their relationships, and the resulting transforms, are together called an XML application.  (X)HTML is an example of an XML vocabulary.

Case in point.  Summer and fall of 2012, I converted the semi-structured LaTeX source of my linear algebra textbook to an ad-hoc set of tags.  The resulting XSL transformation produced the online version.  None of this is very reusable, and I have not released the transforms publicly.  They should not interest most authors.  The source should be of interest (it is not perfect, but is reasonable) and the outputs, such as the online and print versions, should be the demonstration of the power of XML source converting to two very different formats via an XSL transform.

So I see real utility in creating an XML application for authors of writings about mathematics, with a special interest to allow writing about compuational tools, specifically Sage.  An author could adopt this approach, but any mathematician who can write in LaTeX already has the mindset to use a markup lanuguage rather than a word processor.  More in the next post about design requirements and my plans.  If you cannot wait, head over to the project page.