Thursday, February 27, 2014

A Standard for Meaningful Mathbook Markup.

If authors of open textbooks are really going to share material, then it needs to be easy to combine the source $\LaTeX$ from different documents. Suppose you wanted to re-use material from a linear algebra textbook, which included this sentence:

Suppose \$A \in \GL(4,\C)\$ and let \$B=\adjoint{A}\$.

That sentence contains 3 non-standard macros. You probably understand what is written, but if you haven't defined those macros then you can't just insert that sentence into your book. This points to the desirability of having a standard set of macros.

I'll state some principles I see as important, and then propose an initial list of what I will call the "mathbook macros". The name is a reference to Rob Beezer's MathBook XML (see previous posting) which will allow authors to easily produce versions of their work for multiple platforms.

Here I am only referring to math markup. The structural markup of a document -- chapters, sections, theorems, definitions, examples, etc -- will be part of a separate discussion.

Part 1: Principles for MathBook Markup.

  1. Mathematically meaningful markup is better than markup which merely specifies how the math should be typeset.
  2. Mathbook markup should specify the mathematical meaning, not the layout.
  3. Mathbook markup should not require a bunch of extra typing by the author.
  4. It should be easy to read the raw $\LaTeX$ in context.
  5. It should be easy to guess how to do the markup.
  6. If it does not seem possible to satisfy the previous principles in a particular situation, then there is no standard mathbook markup, and the author will have to invent and use a non-standard markup.
  7. The MathBook Markup is successful if it covers more than half the math macros in a typical well-written undergraduate math textbook.
Let's examine the sentence after the first paragraph above. I claim it satisfies the first 5 Principles. Let me clarify the second Principle. The complex numbers, $\mathbb{C}$, are typeset as bold by some authors, and as blackboard bold by others. You can use the macro \C in both cases, and different notation by different authors does not prevent them from sharing material.

An alternative to that sentence is

Suppose \$A \in GL(4,\mathbb C)\$ and let \$B=A^*\$.

The only merit in that version is that no macros are needed to compile it. It is inferior in every other way, especially if you prefer a different notation for the complex numbers or the adjoint of a matrix.

Part 2: Proposed examples of MathBook Markup

Linear Algebra. I looked at Rob Beezer's $\LaTeX$ macros in FCLA and propose the following subset for inclusion in MathBook Markup. I leave off the backslash, and I don't indicate the meaning, because by the 4th Principle you should be able to guess the meaning.

inverse, transpose, adjoint, rank, nullity, norm, conjugate.

This is a fairly small subset of Rob's macros, so I am far from satisfying the last Principle. Also, all of those macros take one argument. Somehow it seems harder to come up with obvious names for macros that take 2 arguments. But maybe someone has a clever idea? Or maybe we can replace the 5th Principle by an easy way to look up a macro?

Calculus. For a calculus book it may be reasonable to have a \d macro for the "d" in an integral, and maybe macros \dx, \dy, and \dt, and maybe for some other common variable names. I'd be interested in hearing the opinions of calculus textbook authors.

Automorphic forms. The L-functions and Modular Forms Database (LMFDB) is a large collaborative project which has adopted the following standard macros:

\C : complex numbers
\R : reals
\Q : rationals
\Z : integers
\F : field (as in \F_p for the field with p elements)
\HH : upper half-plane

The following symbols for classical groups are also available:

\SL, \GL, \PSL, \PGL, \Sp, \GSp

And these symbols for operators:

\Gal, \Aut, \sym, \End, \Reg, \Res, \Ord, \sgn, \trace

Macros relevant to number fields:

\ideal{p} : the prime ideal \frak p
\classgroup{K} : the class group Cl(K)
\integers : the ring of integers \mathcal O (not the rational integers \Z)
\modstar{A}{B} : gives (A/B)^\times

I think the math open textbook community would benefit from choosing standard macros for common mathematical concepts. This would allow sharing of $\LaTeX$ source, but it would put no constraints on the notation used by each author.

All comments welcome, including "You are wasting your effort because people won't bother to do this."

David Farmer
American Institute of Mathematics

Monday, February 24, 2014

A write once, read anywhere document preparation system.

I've been intrigued for some time by the possibility of converting source documents into a variety of output formats.  This began in 2006 when I used tex4ht to convert the $\LaTeX$ source for my linear algebra textbook (FCLA) into HTML.  Around 2009 I began to experiment with using this conversion to create worksheets viewable in the Sage notebook.  The idea was to have Sage code in the source, and have the code be "live" in the notebook - editable and executable.  It was a real challenge to begin with $\LaTeX$ and convert to the Sage notebook format (mildly perturbed HTML, rendered with jsMath) so that the text, $\LaTeX$ and Sage all survived intact.  With support from the UTMOST grant I was able to get this working for FCLA and Judson's abstract algebra text.

Fast-forward to May 2013.  Now we have MathJax as the very worthy succesor to jsMath.  Jason Grout and his students have created the Sage Cell server, allowing an easy embedding of live Sage code in a web page.  Harald Schilly and David Farmer have created knowls, making cross-references and detail-hiding much more efficient than hyperlinks.  The previous year I had gained a lot of hard-won experience converting the source for FCLA to a one-off version of XML.  This made many more things possible, with the powerful text transformations available through XSL processing.  The result is the current web version of FCLA, in addition to a print-on-demand hardcover version.

With support from a Shuttleworth Flash Grant, I have started to build a general XML application for creating textbooks and other scholarly documents (research papers, monographs, etc).  The main goals are to deliver on the promise of separating presentation from content, and to be as simple as possible for authors to quickly get effective results.  Most mathematicians will tell you that $\LaTeX$ is all about separating content from presentation, but if you spend enough time trying to parse it programatically you discover it is full of inconsistencies and hidden/implied structure.  And that is before authors start using the abundance of add-on packages.  Quick: what does "\chapter" do?  Answer below.

Unlike DocBook, there is extensive support for mathematics, both displayed and numbered equations and the additional structure of definitions, theorems, claims, remarks and all the cross-referencing we expect.  Authors enter shortcut $\LaTeX$ macros for commonly used mathematical constructs one-time only, and they get used for MathJax and for $\LaTeX$ output.  HTML output can embed the Sage Cell server and GeoGebra applets, with Code Mirror, JSXGraph, and video all planned or partially implemented.

My intent is to very carefully design the XML elements.  They will be limited to expressing document structure and semantics, while preserving $\LaTeX$ markup for mathematics proper (only).  This will not be the ugly verbose XML that is created by programs.  I am writing XSLT converters to $\LaTeX$ and HTML as demonstrations, others may want to write other converters.   I have written, but not released yet, converters to Sage notebooks, SageMathCloud worksheets, and iPython notebooks.  I am experimenting with an extension for letters that includes images for letterhead and scanned signatures for PDF versions (since the $\LaTeX$ letter class drives me crazy).  I have used these tools for an article that will appear in the Monthly, for a monograph I am writing on combinatorial designs, and for lecture notes (a book, really) for my advanced linear algebra class this term.  It is very liberating to forget about $\LaTeX$, HTML, CSS, Javascript, and just concentrate on writing content, knowing your tools will produce something useful and appealing on the other end, with a single command-line invocation.

The link below is an example of the latest iteration, with plenty of rough edges in the content and presentation.  David Farmer gets credit for driving the creation of useful and general HTML markup, which will be useful beyond just this project.  A UPS student, Michael DuBois, designed the CSS, both visually and functionally, which accompanies the HTML.

So this is an invitation to become involved, as a user or by making suggestions, or just by keeping an eye on developments.  I do not yet have everything consolidated on a single website, but plan to soon and will announce it on the Google Group, and perhaps here.  In the meantime...

If you are interested, please join the discussions at the Google Group:!forum/mathbook-xml-support

Code is on GitHub (everything is on the dev branch):

Rob Beezer
University of Puget Sound

(Answer: yes, \chapter usually gets you a chapter heading.  Unless it comes sometime after \backmatter, in which case it gives you an appendix heading.)

Monday, February 17, 2014

Numbering in Papers and Books

I am preparing to release a Python program that converts math papers and books into HTML. A key design decision is that I am not attempting to replicate everything in the PDF version. In particular, I think it is time to stop repeating common errors. A particular error I want to avoid is un-helpful numbering. I'd be interested in hearing comments on my numbering proposal.

There is a long list of possible numbering schemes, and a short list of reasonable numbering schemes. For example:
  1. Number every equation with a single integer, sequentially throughout the entire multi-section document.
    *Bad* It is hard to find the equation you are looking for.
  2. Number everything in the format section.subsection.number , where every environment has its own separate numbering.
    *Bad* If Theorem 3.2.4 is followed by a Lemma, that should be Lemma 3.2.5, not Lemma 3.2.whatever-the-next-lemma-number-is.
  3. Number everything in the format section.subsection.number , where you group environments in a sensible way and have only a handful of sequential numberings.
    *Good*  For example Lemma 3.2.4, Theorem 3.2.5, Corollary 3.2.6.
At present, my program uses the 3-level numbering of Item 3. above, where books have chapter.section.environment_number and papers have section.subsection.environment_number
 I only keep track of the following global numbers:
  • chapter
  • section
  • subsection
  • subsubsection
  • equation
  • theorem-like (i.e., lemma, proposition, remark, conjecture, example,...)
  • figure (a "figure" is anything with a caption.)
So, except for the "sections", there are only 3 other sequential numbers throughout the document.

In addition, there are "local" numbers, as in a list or the exercises at the end or a section. Exercises sprinkled throughout a section would use the theorem-like number.

Question 1. Is there something missing, or unwanted side-effects, from this numbering scheme?

Question 2. If a paper has sections but no subsections, then it makes sense to use a 2-level instead of a 3-level numbering. But what if some sections have subsections, and others don't? Do you mix 2-level and 3-level numbering?

Question 3. What choices, if any, should be left to the author?

Comments welcome.
David Farmer
American Institute of Mathematics

[Post your responses in the comment section below.]

Monday, February 10, 2014

WeBWorK Exercises as a Source of Supplementary Problems

One criticism repeated often in the Baltimore sessions was the paucity of exercises in open-source texts.  Authors uniformly indicated that providing a carefully edited and complete set of exercises (including solutions) for their texts was the most demanding part of creating the text.  For some texts at the pre-college and early college levels (algebra, pre-calculus, and calculus) the MAA's free and open-source WeBWorK on-line homework system can help to fill this gap.

A couple of years ago, I decided to give WeBWorK a try in my calculus II class.  Since it's free (I'm a cheapskate at heart) and I have a few computer servers at my disposal, I downloaded the instructions for installing WeBWorK from their Get WeBWorK page.  In particular, I had an Ubuntu 12.04 linux machine, so I downloaded step-by-step instructions for an Ubuntu 12.04 system.  I will admit to having a fair amount of unix system administration experience, but if you're passingly familiar with unix, you can probably get through this in an hour or two.  If you're not a unix person (and not a cheapskate) you can actually buy access to a WeBWorK server at a relatively low-cost.

Long story short, I set up my own server and proceeded to use WeBWorK to provide students with additional exercises.  I taught out of Guichard's Calculus text (free, open-source).  Guichard's text has a decent number of exercises, but WeBWorK had far more to choose from.  In addition, WeBWorK provides instant feedback which students indicated they liked.  Finally, with WeBWorK the instructor can closely monitor whether students are actually doing homework and whether they're doing it on time.  (Can you tell I'm a fan?)

Back to the point of this post, open-source authors faced with the daunting task of creating exercises and solutions for their texts should consider pre-existing open-source repositories of exercises, like WeBWorK, to fill this gap.  IMathAS is another open-source homework system for mathematics (but I haven't used it).  If any of you know of other open-source collections of exercises for mathematics, please post references in the comments.

If any of you are teaching calculus I, II, or III out of Guichard's book, I have since created WeBWorK problem sets that correspond to nearly every section of the text.  You can download the .def files for calculus I, calculus II, and calculus III.  They may not perfectly fit your needs, but they certainly provide a good starting point for your problem sets.

Friday, February 7, 2014

Open-source Texts in MAA Reviews.

One way to promote your well-established open-source textbook is to get a review published in MAA Reviews.  A number of reviews of open-source texts have already appeared in that venue:  Guichard: Calculus, Beezer: Linear Algebra, Judson: Abstract Algebra, and Hammack: Book of Proof to name a few.

Several of these reviews I solicited by contacting the authors, finding users of their texts and subsequently asking those users to submit reviews.  The editor of the MAA Reviews, Fernando GouvĂȘa, has been supportive of efforts to place reviews of open-source textbooks on the site.  If you are a user (not author) of an open-source text, I encourage you to submit a review of the text to MAA Reviews.  Here are some instructions on how to contribute.

If you are an author of an open-source text, ask one or more of your users to write a review for MAA Reviews.  I wrote a review of Guichard's Calculus text jointly with Victor Reiner.  The possibility of several users of the text jointly writing a review exists and, in some ways, could be construed as a stronger review.  Of course, best practices dictate that you (the author) probably shouldn't write your own review. :)  I think Prof. GouvĂȘa might catch on to that.

Monday, February 3, 2014

Slide Repository for Talks from the Joint Mathematics Meeting in Baltimore.

The presentation files for the open-source text talks (session 1, session 2) given in Baltimore are now available from this repository:

Thanks once again to everyone that participated and for making these files available.