Discussion:
Markdown and Mathematics
Michel Fortin
2004-04-04 14:21:26 UTC
I've been asking myself how math formulas could be written in a
Markdown document. Here are my thoughts.

A way I see that could make not too much unreadable equations (while
reading text) and powerful ones (as in complex ones) is latex. Here are
some equations in latex:

x^2 + y^2 = z^2
e^x = \relstack{\rm lim}{n\rightar\infty} \ (1+\frac xn\)^n

You can see that when the expression is simple it's perfectly readable
as plain text. When the equation is more complex it becomes a little
less readable, but it's still a lot more readable than plain MathML
tags (an XML language for mathematics). Latex is already well known by
many mathematicians and is a tool of choice for anyone who want to
write mathematics.

So I've thought of a way to include a latex equation into a Markdown
document:

The equation { x^2 + y^2 = z^2 } is really interesting!

This syntax is the most interesting as it's totally readable, it feels
natural to read and to write since latex also use curly brackets as a
grouping delimiter. But it has one downside: it may cause some
conflicts if you use those curly brackets elsewhere. Here is an
alternate syntax that could be used:

The equation {$x^2 + y^2 = z^2$} is really interesting!

It's a little less readable, but the chances to be in conflict with
something else you write are close to zero.

Now, enough about the syntax. How can it be rendered in HTML? Embedding
MathML in the document would be the ideal choice, but some browsers
(like Safari) do not support it (Mozilla, Firebird and Win IE using the
MathPlayer plugin can however). The other way is to use the
[mimetex][1]. MimeTeX is a small program that you put in your CGI
directory and that generate image for the latex equation you put in the
url. You simply have to write an equation image like this in HTML:

<img src="/cgi-bin/mimetex.cgi?x^2+y^2=z^2" alt="x^2 + y^2 = z^2" />

[1]:http://www.forkosh.dreamhost.com/mimetex.html

I took the simple bracket syntax { x } and made an experimental
version of Markdown using mimetex. You can try on my dingus page.
Choose "PHP Markdown Math" form the filter box and you're in!

<http://www.michelf.com/php-markdown/>

So, is latex a good choice? Is the curly braket syntax dangerous? What
is the best way of doing this? I would like to know what everyone
thinks and especially what John Gruber has to say on the subject.

* * *
Hum, just before hitting send I remember John saying he wants to keep
these curly brackets for class and id assignments. It could become
confusing if the curly brakets are used elsewhere too. But if I use
latex, do I have the choice? There will be some of these brakets inside
the formulas any way.

* * *
Another (latex-compatible) maybe easier to use equation syntax:

[ASCIIMathML] (http://www1.chapman.edu/~jipsen/asciimath.xml) -
This one is fantastic! but output is in MathML and requires Mozilla,
Firebird, or Win IE + MathPlayer. Go try the javascript demo!

Michel Fortin
***@michelf.com
http://www.michelf.com/
John Gruber
2004-04-07 17:39:56 UTC
Post by Michel Fortin
I took the simple bracket syntax { x } and made an experimental
version of Markdown using mimetex. You can try on my dingus page.
Choose "PHP Markdown Math" form the filter box and you're in!
<http://www.michelf.com/php-markdown/>
Neat.
Post by Michel Fortin
So, is latex a good choice?
I don't know and can't say, because I don't write math.
Post by Michel Fortin
Is the curly braket syntax dangerous?
Yes.
Post by Michel Fortin
Hum, just before hitting send I remember John saying he wants to keep
these curly brackets for class and id assignments.
Exactly.
Post by Michel Fortin
What is the best way of doing this? I would like to know what
everyone thinks and especially what John Gruber has to say on the
subject.
The math stuff doesn't belong in Markdown itself. Maybe, possibly,
perhaps, Markdown could support superscripts using something like
x^2, but not something as complex as full-blown math markup.
(Michel, I'm guessing you agree with this.)

The issue here is not Markdown and Mathematics. It's Markdown and
is a generic escape sequence for expansion.

For the sake of discussion, let's say {$ and $}, as Michel
suggested. (Just plain { and } are not enough; the expansion
delimiters need to be something that isn't likely to appear
normally.)

What I'm suggesting is that Markdown, by itself, simply define one
set of delimiters, and that anything appearing between those
delimiters would be ignored.

That would mean that custom expansions could be built on top of
Markdown, with the custom bits going inside those delimiters. You
might write "Markdown Plus Math". Someone else might write "Markdown
Plus Foo." The point is, you wouldn't have to rewrite the core
Markdown parts; just the Foo, which users would include between the
{$ and $} delimiters.

So, I think the question is, what should those delimiters be?

-J.G.
Jelks Cabaniss
2004-04-07 20:40:31 UTC
Post by John Gruber
The math stuff doesn't belong in Markdown itself. Maybe, possibly,
perhaps, Markdown could support superscripts using something like
x^2, but not something as complex as full-blown math markup.
Some kind of superscript^^notation^ (and ~cite~(s)!) are the only things I
use *frequently* that aren't currently available in Markdown except via
inline HTML. The drawback of course is that some will invariably want
subscripts in native MD syntax too. :)
Post by John Gruber
That would mean that custom expansions could be built on top of
Markdown, with the custom bits going inside those delimiters. You
might write "Markdown Plus Math". Someone else might write "Markdown
Plus Foo." The point is, you wouldn't have to rewrite the core
Markdown parts; just the Foo, which users would include between the
{$ and $} delimiters.
Great idea!
Post by John Gruber
So, I think the question is, what should those delimiters be?
Whatever they end up being, you'll probably want to include the "notation"
along with the delimiters, something like

{$mathml: ... Math expression ...$}
{$latex: ... line noise ...$}

/Jelks
David J. Weller-Fahy
2004-04-07 22:03:19 UTC
Post by Jelks Cabaniss
Post by John Gruber
So, I think the question is, what should those delimiters be?
Whatever they end up being, you'll probably want to include the "notation"
along with the delimiters, something like
{$mathml: ... Math expression ...$}
{$latex: ... line noise ...$}
already ignored by Markdown? If that's the case, why not just use the
'<' and '>' characters?

Using the <>, the following would all be ignored by Markdown:

<mathml: ... Math expression ... >
<latex: ... line noise ... >

Or, if closing tags are critical for Markdown's recognition of something
that it should ignore:

<mathml>... Math expression ...</mathml>
<latex>... line noise ...</latex>

In this way (theoretically :) a new delimiter would not need to be
added. Let me know if this would not work as expected.

Regards,
--
dave [ please don't CC me ]
Michel Fortin
2004-04-08 00:38:52 UTC
Post by John Gruber
The math stuff doesn't belong in Markdown itself. Maybe, possibly,
perhaps, Markdown could support superscripts using something like
x^2, but not something as complex as full-blown math markup.
(Michel, I'm guessing you agree with this.)
That's exactly the way I see it: an external processor. What I've done
currently is a modified Markdown program to expriment with math
inclusion, but be assured I will not be releasing it integrated with
Markdown. This is better suited for an external program.
Post by John Gruber
The issue here is not Markdown and Mathematics. It's Markdown and
is a generic escape sequence for expansion.
[...]
What I'm suggesting is that Markdown, by itself, simply define one
set of delimiters, and that anything appearing between those
delimiters would be ignored.
Writing about math is just like writing about code: you insert math
snippets everywhere in what you say. As an example:

Suppose {ax^2+bx+c=0} and {a!=0}. We first divide by {a} to
get {x^2+b/ax+c/a=0}.

(grabbed from
<http://www1.chapman.edu/~jipsen/mathml/asciimathdemo.html>)

delimiters. Making the text readable is exactly what makes Markdown
great and I think that's important. However, as we said, if it's
implemented as another program that parse the text after markdown made
it HTML, then this syntax could be acceptable since only people that
care will have it installed.

That said, I think it's also very important to have some more
sophisticated expansion rules too.
[more on expansion below]
Post by John Gruber
That would mean that custom expansions could be built on top of
Markdown, with the custom bits going inside those delimiters. You
might write "Markdown Plus Math". Someone else might write "Markdown
Plus Foo." The point is, you wouldn't have to rewrite the core
Markdown parts; just the Foo, which users would include between the
{$ and $} delimiters.
I agree about the Markdown + Math name, it's great because it puts a
separation between the two tools even if they are used together.
Post by John Gruber
Whatever they end up being, you'll probably want to include the "notation"
along with the delimiters, something like
{$mathml: ... Math expression ...$}
{$latex: ... line noise ...$}
I like that idea. It is also my opinion that it's important to include
extension's name in the syntax, or otherwise there will be conflict the
minute someone want to use more than one extension.

But there is another potential problem: what if someone write this in a
code block? In order to respect the code block, we could ask that every
extensions parse the HTML and ignore what is inside code, pre and
some other tags. That's a lot of parsing if you have many extensions.

Or maybe Markdown could accept *plugins*. That means you put the
plugins in a special directory. When parsing, if Markdown encounter a
{$latex: ...$} block, it looks for a file named "latex" in that
directory and process the output using that program. If the plugin is

That way a casual user that does not write about math often can still
include some math when it want it using this rule.

Let's say I want to write an equation, I just have to write {$math: a^2+b^2=c^2$}.
To write about chemistry, I write: {$chemistry: 2H + CO + 2O2 -> H2CO3$}.
And to write about music: {$music: ... how could I write music in text? ...$}.

becomes this if appropriate plugins cannot be found:

Let's say I want to write an equation, I just have to write
a^2+b^2=c^2.
To write about chemistry, I write: 2H + CO + 2O2 -> H2CO3.
And to write about music: ... how could I write music in text? ....

Michel Fortin
***@michelf.com
http://www.michelf.com/
Jason Clark
2004-04-08 16:04:49 UTC
Post by Michel Fortin
Writing about math is just like writing about code: you insert math
Suppose {ax^2+bx+c=0} and {a!=0}. We first divide by {a} to
get {x^2+b/ax+c/a=0}.
{lots more good stuff removed for breveity}
Post by Michel Fortin
That way a casual user that does not write about math often can still
include some math when it want it using this rule.
a^2+b^2=c^2 $}. To write about chemistry, I write: {$chemistry: 2H + CO + 2O2 ->
H2CO3 $}. And to write about music: {$music: ... how could I write music in
text? ... $}. Let's say I want to write an equation, I just have to write a^2+b^2=c^2. To write about chemistry, I write: 2H + CO + 2O2 -> H2CO3. And to write about music: ... how could I write music in text? .... Two suggestions: First, {$ this $} is okay, but what about {{ this }}? Just like the proposals for [[implicit links]], I think doubling the delimiters is easier to type and to look at (ie., is less visually distracting). Second: I like the idea of allowing multiple escaped syntaxes, but it could get burdensome to read. Taking your original example: Suppose {$math: ax^2+bx+c=0 $} and {$math: a!=0 $}. We first divide by {$math: a $} to get {$math: x^2+b/ax+c/a=0 $}. My suggestion is that when the sytax type is unspecified, the previously specified type remains in effect. So, Suppose {$math: ax^2+bx+c=0 $} and {$ a!=0 $}. We first divide by {$ a
$} to get {$ x^2+b/ax+c/a=0 $}. Or perhaps even more readable (and also incorporating my first suggestion: {{math:}} Suppose {{ax^2+bx+c=0}} and {{a!=0}}. We first divide by {{a}} to get {{x^2+b/ax+c/a=0}}. Jason Clark <***@jclark.org> http://jclark.org/weblog/ Jelks Cabaniss 2004-04-08 00:16:55 UTC Permalink Post by David J. Weller-Fahy Post by Jelks Cabaniss {$mathml: ... Math expression ... $} {$latex: ... line noise ... $} Maybe I'm being too simplistic about this, but aren't (X)HTML tags already ignored by Markdown? If that's the case, why not just use the '<' and '>' characters? For MathML, just use <math xmlns="http://www.w3.org/1998/Math/MathML"> ... [/itex] But I thought what was wanted was an extension mechanism to allow conversions of ASCIIfications of MathML etc. Something like enabling "plug-ins" for Markdown. Maybe I was reading too much into it. /Jelks David J. Weller-Fahy 2004-04-08 16:06:23 UTC Permalink Post by Jelks Cabaniss Post by David J. Weller-Fahy Post by Jelks Cabaniss {$mathml: ... Math expression ... $} {$latex: ... line noise ... $} Maybe I'm being too simplistic about this, but aren't (X)HTML tags already ignored by Markdown? If that's the case, why not just use the '<' and '>' characters? For MathML, just use <math xmlns="http://www.w3.org/1998/Math/MathML"> ... [/itex] But I thought what was wanted was an extension mechanism to allow conversions of ASCIIfications of MathML etc. Something like enabling "plug-ins" for Markdown. Maybe I was reading too much into it. I don't think you're reading too much into it. Extensions to Markdown will process the text themselves, so I don't believe Markdown has to do anything with those tags except recognize that it shouldn't process that chunk, right? If so, just having Markdown leave those particular pieces of text alone should be enough. I think that method fits in nicely with the KISS ideology behind Markdown. Regards, -- dave [ please don't CC me ] John Gruber 2004-04-10 22:49:08 UTC Permalink Post by Michel Fortin Post by Jelks Cabaniss Whatever they end up being, you'll probably want to include the "notation" along with the delimiters, something like {$mathml: ... Math expression ... $} {$latex: ... line noise ... $} I like that idea. It is also my opinion that it's important to include extension's name in the syntax, or otherwise there will be conflict the minute someone want to use more than one extension. But I don't think Markdown itself should look for or do anything with the names of these additions. All I want to do at this moment is decide on a set of delimiters which Markdown will not process the contents thereof. Post by Michel Fortin But there is another potential problem: what if someone write this in a code block? Yeah, that's a tricky question. But I don't think it's up to Markdown itself to decide. Post by Michel Fortin Or maybe Markdown could accept *plugins*. That means you put the plugins in a special directory. When parsing, if Markdown encounter a {$latex: ...$} block, it looks for a file named "latex" in that directory and process the output using that program. If the plugin is not found, Markdown removes the delimiters and leave only the content. Whoa, slow down. :^) It's possible, at some later date, that we can do this. And we can do it without breaking 1.0 syntax if we pick good delimiters now. I'm just not sure what those delimiters should be. {$...$} isn't too bad. But it's sort of hard to type. {{...}} is easier to type. -J.G. Michel Fortin 2004-04-11 18:08:41 UTC Permalink Post by John Gruber Post by Michel Fortin Post by Jelks Cabaniss Whatever they end up being, you'll probably want to include the "notation" along with the delimiters, something like {$mathml: ... Math expression ... $} {$latex: ... line noise ... $} I like that idea. It is also my opinion that it's important to include extension's name in the syntax, or otherwise there will be conflict the minute someone want to use more than one extension. But I don't think Markdown itself should look for or do anything with the names of these additions. All I want to do at this moment is decide on a set of delimiters which Markdown will not process the contents thereof. You are right. I'm not saying Markdown should do anything with this currently, but the idea was to set a recommendation for extension makers so that they do not enter in conflict each other, or with a hypothetical future release of Markdown with plugin support. Maybe this is not needed after all. Post by John Gruber Post by Michel Fortin But there is another potential problem: what if someone write this in a code block? Yeah, that's a tricky question. But I don't think it's up to Markdown itself to decide. My point was only to show that each extension would have to duplicate current Markdown tokenization as an introduction to the plugin idea. Post by John Gruber Post by Michel Fortin Or maybe Markdown could accept *plugins*. That means you put the plugins in a special directory. When parsing, if Markdown encounter a {$latex: ...$} block, it looks for a file named "latex" in that directory and process the output using that program. If the plugin is not found, Markdown removes the delimiters and leave only the content. Whoa, slow down. :^) I was just thinking out loud. ;-) I understand things must not be rushed. Post by John Gruber It's possible, at some later date, that we can do this. And we can do it without breaking 1.0 syntax if we pick good delimiters now. I'm just not sure what those delimiters should be. {$...\$} isn't too bad. But it's sort of hard to type.
{{...}} is easier to type.
I think I prefer {{this one}}.

Another syntax that could be post-processed and would already work is
this:

<?math ... ?>

It's a processor instruction in the XML specification. An advantage of
it is that in code blocks <> characters are encoded and the
postprocessor will ignore them for free. Great! A downside may be that
if not processed a well behaved browser will not display it's content
(but the XML would stay valid). The other downside is that it's harder
to type than {{...}}. Also to note: writing ?> inside is
prohibited.

Michel Fortin
***@michelf.com
http://www.michelf.com/
Autoresponder
2004-04-10 22:49:11 UTC
My email address has changed from ab to aa. Yep, the spambots found me
out, so I'm moving again.

The rest of my address -- the "at" symbol forward -- has not changed.
John Gruber
2004-04-10 22:49:10 UTC
Post by David J. Weller-Fahy
already ignored by Markdown? If that's the case, why not just use the
'<' and '>' characters?
<mathml: ... Math expression ... >
<latex: ... line noise ... >
Or, if closing tags are critical for Markdown's recognition of something
<mathml>... Math expression ...</mathml>
<latex>... line noise ...</latex>
In this way (theoretically :) a new delimiter would not need to be
added. Let me know if this would not work as expected.
I don't think this will work, because it's confusing XML/HTML-ish
markup with Markdown's own syntax.

The XML/HTML-ish way would be:

<mathml>... Math expression ...</mathml>
<latex>... line noise ...</latex>

But Markdown would end up processing the contents of those tags.
Markdown only skips the contents of a hard-coded list of block-level
HTML tags.

This idea, on the other hand:

<mathml: ... Math expression ... >
<latex: ... line noise ... >

would work, I think, but it's contrary to the way XML/HTML tags
work, and thus, I think, confusing. Or at least unnatural.

-J.G.
Autoresponder
2004-04-10 22:49:14 UTC