How to export Confluence pages containing equations to PDF

Recently I was helping a chemistry lecturer with some of her course notes. She authors her course notes in Confluence, then uses the "Export to PDF" functionality to create versions of her notes for distribution to the course participants. This workflow was suiting her nicely until she tried to export her pages.

The course involves mathematics, so she was using the ASCIIMath macro -- the newly released Confluence LaTeX plugin would likely be preferable for Confluence 4.x. This macro uses client side JavaScript to render the correct formula to the page.

The ASCIIMath and Confluence LaTeX plugins both do a good job of client side rendering, but this is no good for printing to PDF. On export to PDF, ASCIIMath simply prints the raw LaTeX syntax. For our purposes, this was not acceptable.

The lecturer requested a new macro with the same or similar syntax to the ASCIIMath macro (science academics are often LaTeX geeks), but which successfully exports to PDF. The obvious choice here would be to extend the current ASCIIMath macro with the relevant functionality. In theory, this would fix the lecturer's problem without her having to update any content. Unfortunately, I didn't have the time to do this.

Instead, I quickly hacked together a user macro which fits the requirements. Here it is:

"Equation" User Macro


## Macro Name: equation

## Macro Title: Equation

## Categories: Confluence Content, Formatting

## Visibility: Visible to all users in the Macro Browser

## Macro has a body: Y

## Body processing: Render HTML

## Output: HTML

## Icon URL: http://png.findicons.com/files/icons/2394/stroke_text/72/equation.png

##

## Developed by: David Simpson <david@davidsimpson.me>

## Date created: 2012-02-19 v1.0.1

## Installed by: Your Name Goes Here

##

## A very light-weight replacement for the {math} macro.

## It is syntactically more verbose, but should give exactly the same results across browsers and allow for export to PDF.

## Test out your syntax here:

## http://www.forkosh.com/source_mathtex.html#latexmarkup

##

## Usage {equation}x^2{equation}

##

## 1. Raw URL encode the plus signs in the body (this is revisited in step 4.)

#set( $body = $body.replace("+", "%2B") )

##

## 2. URL encode the body (spaces are converted to "+" rather than "%20")

#set( $body = $generalUtil.urlEncode($body) )

##

## 3. Encode the spaces as %20

#set( $body = $body.replace("+","%20") )

##

## 4. Fix double encoding on plus signs

#set( $body = $body.replace("%252B","%2B") )

##

##

## IMPORTANT: After testing, replace "http://www.forkosh.com/mathtex.cgi" belowwith the location of your local installation

##

<img src="http://www.forkosh.com/mathtex.cgi?gammacorrection{1.25}%20$body">

The user macro above relies on mathTeX and which of course relies on LaTeX. I very much recommend that you install both of these locally. Do not piggy back off of John Forkosh Associates, Inc. installation.

Examples

The examples below use wiki markup (remember that?) to add the equation to the page. For Confluence 4.x users, you can either use insert wiki markup and paste each example into your page as is or remove the {equation} prefix & suffix.

Example 1

Usage:


{equation}x^2{equation}

Output:

Example 2

Usage:


{equation}f(x)=intlimits_{-infty}^x~e^{-t^2}dt{equation}

Output:

Example 3

Usage:


{equation}frac{{d}}{{left.{d}{x}right.}}{f{{left({x}right)}}}=lim_{{{h}to{0}}}frac{{{f{{left({x}+{h}right)}}}-{f{{left({x}right)}}}}}{{h}}{equation}

Output:

Example 4

A somewhat more complex example, taken from this page. This time, we get a diagram rather than just an equation.

Usage:


{equation}pngdefinecolor{blueblack}{RGB}{0,0,135}color{blueblack}begin{picture}(4,1.75)thicklinesput(2,0.01){arc{3}{3.53588}{5.8888}}put(.375,.575){line(1,0){3.25}}put(1.22,1.375){makebox(0,0){footnotesize$ds$}}put(.6,.5){makebox(0,0){footnotesize$x=0$}}put(3.36,.5){makebox(0,0){footnotesize$x=ell$}}dottedline{.05}(1.0,.575)(1.0,1.10)put(1.0,.5){makebox(0,0){footnotesize$x$}}dottedline{.05}(1.5,.575)(1.5,1.40)put(1.5,.5){makebox(0,0){footnotesize$x+dx$}}put(1.22,.65){makebox(0,0){footnotesize$dx$}}dottedline{.04}(0.6,1.12)(1.25,1.12)put(1.0,1.14){vector(-1,-1){.45}}put(.58,0.83){makebox(0,0){footnotesize$T$}}put(.77,1.05){makebox(0,0){scriptsize$theta(x)$}}put(1.18,1.16){makebox(0,0){scriptsize$theta(x)$}}dottedline{.04}(1.5,1.41)(2.1,1.41)put(1.5,1.44){vector(4,1){.67}}put(2.22,1.59){makebox(0,0){footnotesize$T$}}put(1.95,1.45){makebox(0,0){scriptsize$theta(x+dx)$}}end{picture}{equation}

Output:

Recap

This user macro is useful for any technical author with Confluence pages containing equations who needs to export pages to PDF. It will also help users who utilise the Scroll Wiki Exporter range of products to publish their content. This user macro is dependent on an external installation of mathTeX which in turn requires LaTeX.

Aside

The code (or at least some of the thinking) behind this user macro would make an excellent fail-back/export solution to bundle with the Confluence LaTeX plugin. I think I'll open a JIRA...