Math equations, and extensions in general

Rob Shearer
Thu, 27 Sep 2007 18:50:04 -0000

In my work I do some scientific and mathematical writing, and like
most people in academia I use LaTeX.

I trade a lot of email with colleagues which contains mathematical
notation. We all do a lot of LaTeX, so we tend to just drop LaTeX
math notation into plaintext; expressions such as `\{ x \mid x^2 \in
S \}` are easy to type, and in simple cases fairly easy to read. More
complex equations I use a tool to render. (LaTeXit on the Mac works
well.)

I've grown to use Markdown syntax whenever I'm writing plain text;
occasionally this means that something that's evolved via email can
just be cut and pasted into a "proper" document for web publishing.
But it seems ridiculous that the most non-plaintext-y thing in these
messages doesn't have any special syntax.

My understanding of the existing state of play (and please extend
this list with what I've missed) includes three implementations:

- [MultiMarkdown][] has some mathematics support based on [asciimath]
[] notation using double-angle-brackets as delimiters:
`<<...asciimath...>>`. I'm afraid I can't find any asciimath
documentation that tells me how to do set notations in that format...
- Python-markdown's [mdx_math][] extension seems to use latex
notation with HTML-style tags, like ` \{ x \mid x^2 \in S \}</
math>`. This use of tags strikes me as quite un-Markdownish.
- [Pandoc][] handles LaTeX math between dollar signs (which is
standard LaTeX notation): `$\{ x \mid x^2 \in S \}$`.

[MultiMarkdown]: http://fletcherpenney.net/
MultiMarkdown_Syntax_Guide#mathsyntax
[asciimath]: http://www1.chapman.edu/~jipsen/asciimath.html
[mdx_math]: http://www.freewisdom.org/projects/python-markdown/mdx_math
[Pandoc]: http://johnmacfarlane.net/pandoc/README.html#inline-latex

While I'd love to see mathematics support in the "official"
Markdown
syntax, I understand that it's not a huge priority for most people
(particularly since an ideal widely-supported HTML rendering isn't
available). I'm more interested in how extension writers should
choose syntax for new constructs. I would think that the general
goals are:

1. Standard Markdown formatters (without extensions) should render
all but the portions of the document using the extension correctly;
i.e. the extension syntax shouldn't break the rest of the Markdown
syntax.
2. Unextended Markdown documents should not "accidentally" use
extended syntax; i.e. a valid standard markdown document should
render exactly the same way when run through an extended formatter.
3. Standard Markdown formatters should be able to identify the
extended constructs used in a document.
4. Standard formatters should render extended constructs no worse
than their plaintext representation.

Incorporating explicit "extension" syntax into the spec should make
meeting all of these goals possible. There's an additional desire,
not demonstrated by my mathematics example, that instead of being
rendered like their plaintext, some extensions (tag attributes, for
example) should just be ignored by formatters which don't support
them. That would probably require two different extension syntaxes.

Span-level elements are generally bracketed by single characters, but
unless the Markdown spec specifically reserves a large set of
characters for this use this seems impractical to me. As much as I'd
like just using dollar signs to set off equations, I'm willing to
accept that extensions will have to be very slightly less plaintexty
than regular Markdown.

Square brackets seem to be the standard way to do special span
formatting. Images set the precedent of using a prefix character for
a special "type" of square-bracket span, so `$[\{ x \mid x^2 \in S \}]
` might be an appropriate encoding.

The footnote extension, however, puts the character inside the square
brackets, and this strikes me as a much more easily-parsed syntax.
Then we could use not just single characters, but maybe full
extension names: `[asciimath: 1/(x^y)]`. It's then easy for tools to
generate a user-friendly list of the extensions used in a document.

In order to regain readability (since some extensions will be used
*very* often in some documents---it's not uncommon in my emails to
mix subscripted variable names with prose, meaning a dozen shifts
into the extension in a single sentence), a header in the markdown
document (or just some special syntax in the text which doesn't get
rendered) could assign extension names to shortcuts. My documents
could be prefixed with

	Extension: latex-math=$

to get the `[$\{ x \mid x^2 \in S \}]` syntax I prefer. (Or my
formatter could just be set up to use this mapping by default.)

Are there any recommendations right now about how to decide on syntax
for extensions?