I’ve been work­ing at Design Sci­ence for a couple of months now, as Seni­or Pro­duct Man­ager con­cen­trat­ing on the Math­Flow products. So I figured I should enable Math­ML sup­port on my blog. It’s not hard, but like everything in tech there are a few nig­gly details. Many of those issues are caused by WordPress’s over-eager help­ful­ness, which has to be reined in on a reg­u­lar basis if you’re doing any­thing at all out of the ordin­ary. Like edit­ing your posts dir­ectly in HTML rather than using some pseudo-WYSIWYG edit­or.

The­or­et­ic­ally, show­ing Math­ML in a browser is easy, at least for the sort of equa­tions that most people put in blog posts, even though not all browsers sup­port Math­ML dir­ectly. You just use the Math­Jax JavaS­cript lib­rary. On Word­Press there is even a plu­gin that adds the right script ele­ment, the MathJax-Latex plu­gin. You can make every page load Math­Jax, or use the [math­jax] short­code to tell it when to load.

The wrinkle comes with Word­Press’ tend­ency to “cor­rect” the markup. When you add the Math­ML, Word­Press sprinkles it with <br/> tags. Math­Jax chokes on those and shows noth­ing. Since the tags don’t show up in the edit­or view, you need some way of stop­ping Word­Press from adding them. The best way I’ve found is with the Raw HTML plu­gin.

But there’s a wrinkle with that too. For some reas­on if you use the short­code ver­sion of the begin and end mark­ers ([raw]) the edit­or decides that the XML char­ac­ters between those mark­ers has to be turned into the char­ac­ter entit­ies, so for example the < char­ac­ters are turned into &lt;. To stop that, you need to a) check all the check­boxes in the Raw HTML set­tings on the post, and b) use the com­ment ver­sion (<– raw –> and <– /raw –>) to mark the begin­ning and end of the sec­tion instead of the short­code ver­sion.

Once it’s done it’s easy to add equa­tions to your pages, so it’s worth the extra few minutes to set it all up.

A couple of examples taken from the Math­Jax samples page

Curl of a Vec­tor Field
$∇→×F→=(∂Fz∂y−∂Fy∂z)i+(∂Fx∂z−∂Fz∂x)j+(∂Fy∂x−∂Fx∂y)k$
Stand­ard Devi­ation
$σ=1N∑i=1N(xi−μ)2$

and one from my thes­is from way back when

$fλ=n!⁢∏i

I see the dis­cus­sion about how best to struc­ture your HTML+CSS to be both appeal­ing to the read­er and easy to main­tain is con­tinu­ing; see The Semantic CSS Debate for some of it and links to more. What par­tic­u­larly struck me was this sen­tence:

I now find myself act­ively advoc­at­ing again­st lib­rar­ies like boot­strap due to the long term main­tain­ab­il­ity issues their approach to CSS causes.

On the sur­face, this appears to be one issue that tem­plat­ing sys­tems can help solve. Wheth­er you use XSLT to gen­er­ate a web site from Word doc­u­ments or XML, or some­thing like Jekyll (which I use for the Tex­tu­al­ity web site), or a database-driven sys­tem, to gen­er­ate the site, you should be able use both a frame­work such as boot­strap and your semantic con­tent. You do have to be pre­pared to put in an inter­me­di­ate step, that of gen­er­at­ing the out­put from the input and plan in advance for the fact that you may wish to switch from form­at a to form­at b.

This seems to me to be a logic­al way of doing things, or may­be it’s simply because I’m steeped in the idea of cre­at­ing the data in a form­at that can be trans­formed to an appro­pri­ate out­put form­at. This idea does make the choice of out­put form­at (in this case pre­cisely which HTML + CSS frame­work to use) some­what less daunt­ing, or rather, the cost of chan­ging it later some­what less (although not neg­li­gible since the trans­form­a­tion sys­tem needs to be changed).

Dis­claim­er: yes, I do write my blog posts using pointy brack­ets. Word­Press provides a tem­plat­ing sys­tem which enables chan­ging styles fairly read­ily; all I write by hand is the con­tent with­in the main con­tent block.

For the XML Sum­mer School this year, I’m teach­ing about HTML5, CSS3 and ePub in the Hands-on Web Pub­lish­ing course. The basic premise of the course is to show what tech­no­lo­gies are involved in tak­ing a bunch of Word doc­u­ments or XML files and turn­ing them into a decent-looking web­site or ePub. The course includes les­sons on rel­ev­ant bits of XSLT trans­form­a­tion (since Word is XML under the cov­ers, if you dig deeply enough), script­ing in Ruby to auto­mate as much as pos­sible, and, of course, enough inform­a­tion about HTML and CSS that people can make a decent-looking web­site in class in the hands-on part.

As a start­ing point for the exer­cises, we’ll use a gen­er­ated tem­plate from HTML5 boil­er­plate, since, if you pick the right options, it is rel­at­ively clean and sim­ple to under­stand. Look­ing at the cur­rent com­mon design prac­tices used across a num­ber of options (HTML5 boil­er­plate, Boot­strap, Word­Press tem­plates for example) coupled with web com­pon­ents and the sheer size and num­ber of HTML5-related spe­cific­a­tions from WHATWG and the W3C, I’m won­der­ing just how much more com­plic­ated it can all get before the pen­du­lum starts swinging back again towards sim­pli­city and sep­ar­a­tion of con­tent from pro­cessing. Even a bare-bones tem­plate has a num­ber of lines in it to deal with older ver­sions of IE, or to load some JavaS­cript or (mostly) jQuery lib­rary. It’s no won­der we’re start­ing to see so many frame­works that try to cov­er up all of that com­plex­ity (Boot­strap again, or Ember, for example).

In the mean­time, at least I have a reas­on­ably con­strained use case to help me decide which of the myri­ad pos­sib­il­it­ies are worth spend­ing time teach­ing, and which are best left for the del­eg­ates to read up on after the class.

This goes into the ‘saves time’ cat­egory and is slightly too long to fit into 140 char­ac­ters.

If you’re using XSLT on some XML file that has had a mis­cel­laneous his­tory and you see the error Illegal HTML character: decimal 146 (or some­thing sim­il­ar), don’t pan­ic or break out your hex view­er to try to find the ran­dom char­ac­ter that’s caus­ing the prob­lem.

Get jEd­it instead. Open the file in jEd­it, and go to the menu Util­it­ies -> Buf­fer Options. In the char­ac­ter encod­ing drop-down, choose Windows-1252. The error message(s) will point you right at the offend­ing character(s). For added fun, repeat with ISO-8859–1 to flush out oth­er odd char­ac­ters that aren’t illeg­al, but may not show up cor­rectly depend­ing on your down-stream pro­cessing (lig­at­ures, etc.). Then switch back to UTF-8 or whatever you need, save, and you’re done!

JEd­it also has decent XML fea­tures if you install the plu­gins, an added bonus.