Jun 242014

I've been working at Design Science for a couple of months now, as Senior Product Manager concentrating on the MathFlow products. So I figured I should enable MathML support on my blog. It's not hard, but like everything in tech there are a few niggly details. Many of those issues are caused by WordPress's over-eager helpfulness, which has to be reined in on a regular basis if you're doing anything at all out of the ordinary. Like editing your posts directly in HTML rather than using some pseudo-WYSIWYG editor.

Theoretically, showing MathML in a browser is easy, at least for the sort of equations that most people put in blog posts, even though not all browsers support MathML directly. You just use the MathJax JavaScript library. On WordPress there is even a plugin that adds the right script element, the MathJax-Latex plugin. You can make every page load MathJax, or use the [mathjax] shortcode to tell it when to load.

The wrinkle comes with WordPress' tendency to "correct" the markup. When you add the MathML, WordPress sprinkles it with <br/> tags. MathJax chokes on those and shows nothing. Since the tags don't show up in the editor view, you need some way of stopping WordPress from adding them. The best way I've found is with the Raw HTML plugin.

But there's a wrinkle with that too. For some reason if you use the shortcode version of the begin and end markers ([raw]) the editor decides that the XML characters between those markers has to be turned into the character entities, so for example the < characters are turned into &lt;. To stop that, you need to a) check all the checkboxes in the Raw HTML settings on the post, and b) use the comment version (<-- raw --> and <-- /raw -->) to mark the beginning and end of the section instead of the shortcode version.

Once it's done it's easy to add equations to your pages, so it's worth the extra few minutes to set it all up.

A couple of examples taken from the MathJax samples page

Curl of a Vector Field
Standard Deviation

and one from my thesis from way back when

Oct 222013

I see the discussion about how best to structure your HTML+CSS to be both appealing to the reader and easy to maintain is continuing; see The Semantic CSS Debate for some of it and links to more. What particularly struck me was this sentence:

I now find myself actively advocating against libraries like bootstrap due to the long term maintainability issues their approach to CSS causes.

On the surface, this appears to be one issue that templating systems can help solve. Whether you use XSLT to generate a web site from Word documents or XML, or something like Jekyll (which I use for the Textuality web site), or a database-driven system, to generate the site, you should be able use both a framework such as bootstrap and your semantic content. You do have to be prepared to put in an intermediate step, that of generating the output from the input and plan in advance for the fact that you may wish to switch from format a to format b.

This seems to me to be a logical way of doing things, or maybe it’s simply because I’m steeped in the idea of creating the data in a format that can be transformed to an appropriate output format. This idea does make the choice of output format (in this case precisely which HTML + CSS framework to use) somewhat less daunting, or rather, the cost of changing it later somewhat less (although not negligible since the transformation system needs to be changed).

Disclaimer: yes, I do write my blog posts using pointy brackets. WordPress provides a templating system which enables changing styles fairly readily; all I write by hand is the content within the main content block.

Aug 272013

For the XML Summer School this year, I’m teaching about HTML5, CSS3 and ePub in the Hands-on Web Publishing course. The basic premise of the course is to show what technologies are involved in taking a bunch of Word documents or XML files and turning them into a decent-looking website or ePub. The course includes lessons on relevant bits of XSLT transformation (since Word is XML under the covers, if you dig deeply enough), scripting in Ruby to automate as much as possible, and, of course, enough information about HTML and CSS that people can make a decent-looking website in class in the hands-on part.

As a starting point for the exercises, we’ll use a generated template from HTML5 boilerplate, since, if you pick the right options, it is relatively clean and simple to understand. Looking at the current common design practices used across a number of options (HTML5 boilerplate, Bootstrap, WordPress templates for example) coupled with web components and the sheer size and number of HTML5-related specifications from WHATWG and the W3C, I’m wondering just how much more complicated it can all get before the pendulum starts swinging back again towards simplicity and separation of content from processing. Even a bare-bones template has a number of lines in it to deal with older versions of IE, or to load some JavaScript or (mostly) jQuery library. It’s no wonder we’re starting to see so many frameworks that try to cover up all of that complexity (Bootstrap again, or Ember, for example).

In the meantime, at least I have a reasonably constrained use case to help me decide which of the myriad possibilities are worth spending time teaching, and which are best left for the delegates to read up on after the class.

Feb 062013

This goes into the ‘saves time’ category and is slightly too long to fit into 140 characters.

If you’re using XSLT on some XML file that has had a miscellaneous history and you see the error Illegal HTML character: decimal 146 (or something similar), don’t panic or break out your hex viewer to try to find the random character that’s causing the problem.

Get jEdit instead. Open the file in jEdit, and go to the menu Utilities -> Buffer Options. In the character encoding drop-down, choose Windows-1252. The error message(s) will point you right at the offending character(s). For added fun, repeat with ISO-8859-1 to flush out other odd characters that aren’t illegal, but may not show up correctly depending on your down-stream processing (ligatures, etc.). Then switch back to UTF-8 or whatever you need, save, and you’re done!

JEdit also has decent XML features if you install the plugins, an added bonus.