Mathup: Easy MathML authoring tool with a quick to write syntax
mathup.xyz126 points by runarberg 2 months ago
126 points by runarberg 2 months ago
If there had been something like this standardized in Markdown from the start, it might have had a chance for wide adoption. Right now, learning to see and use LaTeX math as easily as more ASCII-like notation is just more convenient since it is widely adopted (in GitHub, in VS Code, etc.). It's harder, but it also provides the added benefit of maintaining your LaTeX skills.
I think Google's Chrome team's choices of priorities bear a significant portion of the blame for this. They refused to implement MathML for the longest time, and even when it was implemented, it was partly done and financed by a third party. Without MathML, LaTeX-to-HTML JavaScript hacks became the norm, solidifying LaTeX as the standard even for non-typesetting use cases. Had MathML been implemented by Chrome early on, a more direct and easier translation from something ASCII-like to MathML would likely have been adopted.
Its funny I started writing this tool over 10 years ago (show HN from March 2015 https://news.ycombinator.com/item?id=9235139) where I intended it to be used in Markdown. AsciiMath proper back then (just like AsciiMath today) didn’t compile to MathML so I was forced to write my own
This is pretty much how I always wanted formulas in my notes to look like (but was too lazy to implement it myself, I guess). It's not even so much about fast input, it's about that it needs to be at least somewhat readable in plain text (not rendered), which LaTeX certainly isn't. Typing greek letters and stuff is not really a problem with XCompose, but TeX-based tools are too dumb to render "naïve" expressions pretty. I am not sure why: it seems not a huge computational task to figure out that ] is a `\right]`, and it's not like I often need to use `\left]` anyway. And while rendering `(a+b)/a` as a `\frac` is opinionated, honestly, the only reason why this occurs in my notes is when I was too lazy to type `\frac{}{}`.
I want this to be the default (or at least an option) in all markdown text editors (obsidian, github, etc.) I mean, as an intermediate: in the end MathJax rendering is much prettier than plain MathML.
> it seems not a huge computational task to figure out that ] is a `\right]`
TeX's design was finalised in 1982, when the computational resources were different by a few orders of magnitude. There is a very strong culture of backward compatibility (search for "A torture test for TeX") and there are so many equations written in TeX documents that it would be impossible to change the parsing now.
That said, something like MathJax would be free to create their own TeX-like syntax where parentheses are automatically paired.
I for one often find myself wanting more control, writing `\bigr]` or `\biggr]` instead of `\right]` to get the rendered equation to look good.
> And while rendering `(a+b)/a` as a `\frac` is opinionated, honestly, the only reason why this occurs in my notes is when I was too lazy to type `\frac{}{}`.
Plain TeX has the much nicer syntax `{a+b \over a}` but for some obscure reason LaTeX recommends against that.
At first glance it seems that it not only has functional whitespace, but has overloaded it (used for grouping numerator and denominator or for pre- and suffixes). Also, it seems inconsistent in how it handles commands, some seem to be reserved words while others seem to require \`X`. It might be the right choice for its intended use case of quick and easy math, but it seems like it might come with a few footguns if you use it for anything more than that. Any experiences?
Author here. The intended use case is indeed quick and easy math expressions, and the target users are those that may or may not know LaTeX. I tried to make most expressions possible (I even added tensor notation a couple of weeks ago) but if you want to author complex equations you should probably use LaTeX. In my opinion very complex equations are much more manageable with LaTeX (this is also true of AsciiMath proper).
When your write LaTeX you maintain some structure for complex equations, while here you kind of take the quickest route possible and very quickly loose your footing in the equation’s complexity. In LaTeX you can very easily write out a very complex equation with nothing but your text editor, but here once you are maybe 6 or 7 terms deep you loose your place and will probably need to see a visual rendering to find your footing and continue. Mathup makes this problem worse than in AsciiMath proper, because in AsciiMath proper you are forced to at least parenthesize many of your sub-expressions, while here you are free to go wild with the whitespace.
The whitespace grouping is actually even more powerful than just for fractions, e.g. you can use it group terms around any infix (incl. sub- and superscripts) as well as after any prefix (such as sqrt): `e ^ -x^2/2 / sqrt 2pi` will give you the standard normal distribution. The rule is that if there is space between the operator and the operand it will operate on everything until the next applicable whitespace, the space between sqrt and 2pi applies the the sqrt prefix, and is not applicable to the fraction, but the space before slash is applicable to the ^ so the sqrt 2pi term are not apart of the superscript. I actually don’t recommend relying on this and just use parentheses for all but the simplest expressions (it is fine in sub-expressions though).
But like I said the target usecase is quick and easy expressions, so people that write a+b / c+d are favored over the ones that write `(e^(-(x^2)/2))/sqrt(2pi)` - but honestly I would write this as `e^(-(x^2)/2) / sqrt(2pi)`.
I like this. It addresses a need for quickly writing math expressions with an intuitive syntax. I don’t have to write math expressions often enough to remember the more complex formatting from more powerful packages; and when I do use mathematical expressions, they are usually fairly simple. This will fill that niche.
Thank you. That is exactly why I wrote this. I wanted users to be able to write math in a markdown document, but did not expect any of them to know LaTeX.
I love that this publishes the <math-up> web component.
It's a great way to take content that's actually pretty humanly readable in the HTML, and translate it to an even better rendered format in the UI. It's good for progressive enhancement and framework support at the same time.
Another nice thing about web components is that you can sniff the custom element registry (and even await a promised registration) for custom elements. I was writing a couple of markdown-it plugins yesterday[1][2] to render $dollar delimited math$ and simply places its content in either a <math-up> or a <la-tex>[3] element depending on what is already in the custom element registry. Meaning if you want to write LaTeX rather than AsciiMath all you have to do is import the webcomponent before you call the markdown-it render.
1: https://github.com/runarberg/markdown-it-mathblock
you know what we need even less than another json alternative? another math-language alternative. more so than any other formal(ish) language, a representation (for math) benefits from network effects (because math is both older and broader than any/every other such language).
This is for authoring math expressions which compiles to MathML. MathML has the explicit design goal of being hard to write, and is much more meant to be a compiler target rather than for humans to write.
This space is pretty dominated by LaTeX whom almost all professionals use, but is pretty verbose and not exactly easy to use for beginners (or even non-frequent users). Other than LaTeX we have Office Math, which is a GUI, and AsciiMath. This tool is a dialect of AsciiMath[1] and builds on top of that. If you know AsciiMath, you know this. There is also UnicodeMathML[2], but that has another goal than this or AsciiMath, where the focus is on readability of authored expressions, rather than writability here.
Casual users probably just want the GUI options with less care of what syntax that may eventually involve on the backend. People deep enough to care about writing everything in raw syntax probably want to stick with LaTeX and can have a program transform that to MathML or SVG whatever else they need for display. The "here's a special syntax which is neither all of A or B" is just a hard sell.
On specific tools I've also liked https://www.imatheq.com/imatheq/com/imatheq/math-equation-ed... for quick casual use since it's just a webpage but still a decent GUI editor.
I agree. Since it's all about writing math for presentation and not inputting math for calculation, having to learn a supplementary markup language to learn makes no sense. There is no way you get back the time invested in any meaningful way, unless you write math books for a leaving, I guess.
Some sort of keyboard only markup language for inputting complexe math calculation seem like something worthwhile at first glance. But then you realize that you still need some specialized keyboard keys (and/or macro) if you really want to have completely "inline" (single line).
But at the end you get something that's extremely unreadable and you find out that what's actually needed is computing software that both has a way to write and compute math as we used to on paper.
The 3D aspect is extremely important for comprehension/readability, the only time it makes sense to lay out the equation in some sort of inline markup is for rendering when it's part of a larger document compilation process. And plenty of people use Microsoft Word or some other sort of GUI to avoid even doing this...
Also, you realize that nowadays, pen tablets are extremely cheap and pen input is very simple, so what is really needed is the same type of software that exists on tablets to convert math pen input into formalized markup representation that the computer can understand (no need for the end user to see the underlying mechanics). And voilà, you can have math input without wasting too much time with a markup language.
I think the real power comes when you have both a GUI and an initiative (though not always correct) keyboard input methods. Point and click can be slow, and if you are taking notes while attending a lecture, you probably don’t want to waste your valuable focus looking for the correct icon to write the thing, you just want to type `||a||^2` and hope it does the right thing (and if it doesn’t your temporary markup is obvious enough that you can return to it later).
> MathML has the explicit design goal of being hard to write
Wait, really? Do you have good primary sources to back up that claim?
I worded this badly. I probably should have said that human authoring was not a concern while designing the language. MDN has a specific page for authoring MathML[1] where they suggest you probably don’t want to write them by hand and suggest you should use tools that generate MathML instead.
This is really no different from SVG. The design of the SVG markup language did not take considerations of people writing SVG images by hand, instead they designed the language to be a handy compiler target. Which it is, you can draw nice SVG images from a GUI like inkscape as well as nice graphs from a javascript library like d3.
1: https://developer.mozilla.org/en-US/docs/Web/MathML/Guides/A...
What do you think of Typst https://typst.app/ ? They are planning a web target as well.
It is the first I heard about, but at first glance I like it. It looks like another AsciiMath dialect (just like mathup). But unlike mathup, and like AsciiMath, it seems tightly integrated into its parent environment. If they would release their math authoring as a standalone tool where it would compile to MathML it would be a serious competitor here.
What I like about the typist math dialect is that they seem to go even further than me away from AsciiMath. I was a bit conservative in trying to follow AsciiMath (at least in the beginning).
EDTI: A link to typst math module - https://github.com/typst/typst/blob/main/crates/typst-librar...
What do you think about TexMacs since it has converters for TeX/LaTeX and HTML/MathML?
p/s: It has nothing to do with Tex or Emacs, just a poor naming combination.
[1] Welcome to GNU TeXmacs:
I’m not exactly sure that I have an opinion about it. It seems like a nice tool and I bet it’s users really like it. Inputting math equations seem to be done primarily with the GUI interface, which is probably a fine way of doing it. My personal experience with math via GUI is trying it in office Math and it was fine, I quickly learned TeX personally and have preferred it over GUI input for most of my adult life, so I don’t really have an opinion about particular GUI tools, other than I’m glad they exist and that people can use them.
I absolutely love this project - for years I'd been using a homegrown s-exp to MathML translator, but your project is both more intuitive and capable.
mathup's tiny, clean API makes it easy to integrate the project in all sorts of processing workflows, both in-browser and scripting.
Could pick a better homepage example. The demo code doesn't render very well in MathML. Kerning on the exponents is off. In "beta^alpha" the alpha character touches the beta. Looks better switching to MathJax.
You are right. I hadn’t taken a close look at that expression in chromium (it looks fine on Firefox). I think this may be a Chrome rendering issue. I know Temml does a lot more than me to make sure the expressions look right (my primary concern is that the MathML markup is correct) and even Temml has the same problem[1].
Aside, I love this expression that you landed on. The Gamma distribution is one of the reason I started writing this library 10 years ago. The way the original AsciiMath can’t have arbitrary identifiers (only texts) was a deal breaker for me. The Gamma distribution is a very nice showcase for capabilities of an authoring tool like this because the name is usually written using latin letters `Gamma` while its density function also includes the gamma function which is usually written with a greek capital gamma (Γ). In the original AsciiMath writing Gamma just gives you the greek letter. The gamma distribution is also just a very cool distribution, or rather it contains some very cool distributions (in particular the Chi-squared distribution).
I think all DSLs should be turned into function calls. Of course, function calls can be simpler, such as some infix and dictionary parameters.
Sounds cool! How is this different than https://asciimath.org?
This is a dialect of AsciiMath. The major difference is in the implementation. AsciiMath proper is pretty tightly integrated with MathJax, while this just outputs standard MathML, and then you decide what to do with it.
Second difference is with supported MathML target output. Mathup is far more expressive (we even have tensor index notation in mathup). In mathup you can target your preferred MathML output in a way you can’t in AsciiMath. For example in mathup you can purposefully write any token element you want except <ms>. (`<mi>`, \`<mo>`, "<mtext>", and #`<mn>`), in AsciiMath if you want to wrote Gamma as an identifier (as opposed having it turn into the greek letter) or int as an operator (as opposed to an integral) you have to do it with <mtext>. Here you can do `Gamma` for <mi>Gamma</mi> or \int for <mo>int</mo>.
Thirdly is some differences in syntax. Most noticeable is matrix notation, in AsciiMath you write [(row, one), (row, two)], while in mathup you write [row, one; row, two]. Another major syntax difference is how whitespace works. In mathup you can group pars of your expression together with whitespace, so a+b / c+d is not the same as a + b/c + d. In AsciiMath, you have to use parenthesis to do this.
The example on first hit made no sense for me, the markup and the result were completely unrelated.
Maybe it's a server load issue.
Probably not, this is a static website, I pick a random equation from a pool of 10 on load time. Do you remember which one it showed? or tried to show?
The markup was something like ai = bj + ck + dl where i,j,k,l were superscripts. But there was a theta in there somewhere.
Sorry, I should've taken a screenshot.
The list of demo equations are here https://github.com/runarberg/mathup/blob/main/docs/main.js#L... There are actually 21 of them (not 10). The only one with a theta in it is the gamma distribution (I think I wrote that example 10 years ago; today I would have used x instead of theta as the input variable, and lambda instead of beta as the rate variable). The gamma distribution has no sub-scripts, so you probably got that as the output.
What might have happened is that your browser might have refreshed or something and loaded a different but the listener which reacts to the input changes (as well as page load) may have failed for an unknown reason.
Found it; vec x = a hat i + b hat j + c hat k
I misrembered, the theta was in the (unrelated) rendered version.
No big deal, just some glitch.
Hmm... The mobile experience of that page is not very convincing on first contact
I don't see any issues in Android Firefox, works pretty much the same as my OSX Chrome or Firefox. What is the problem you're having I wonder?
Author here. I will admit that the labeling of the playground is a bit sloppy. The input comes before the output on desktop (as it should) but is flipped in mobile (for ... reasons), but I never wrote an addEventListiner on the matchMedia to change the labels to reflect the swapped order. As a front end engineer for 10 years this is pretty embarrassing.
Another missing feature which quite alot mobile users expect is jump to top. I personally never use it, but many mobile users do.
Code blocks also have kind of excessive margins, and I should probably shrink the font-size so that more users could read the entire thing without horizontal scrolling, though I think this is fairly minor.
Finally, what I can think of, is the content it self. I made the choice when writing the docs, to teach the reader a little about MathML as I demonstrate the project. I think this was a solid choice but it puts the simplest most unimpressive expressions at the top. On desktop this is fine because you can see more impressive expressions further down, but on mobile these are hidden in a horizontal scroll, so the user might be left unimpressed.