Math equations, and extensions in general

[Rob Shearer]

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 `<math>\{ 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?