[HN Gopher] Math on GitHub: The Good, the Bad and the Ugly
___________________________________________________________________
Math on GitHub: The Good, the Bad and the Ugly
Author : s1291
Score : 215 points
Date : 2022-05-20 17:56 UTC (1 days ago)
(HTM) web link (nschloe.github.io)
(TXT) w3m dump (nschloe.github.io)
| fiddlosopher wrote:
| Note also that TeX math can contain \text{..} which can itself
| contain $-delimited TeX math, e.g. $x = \text{my $y$}$. This
| currently breaks the GitHub implementation.
| bla3 wrote:
| > Its main advantage over MathJax is that it isn't dead. Check
| out the repo activity on the two projects:
|
| I know this is a common view, but this is such a strange mindset
| to me. Unless you add scope, a project is eventually just mostly
| done. It's not that MathJax has zero commits, it just has fewer.
| That _in itself_ isn't a bad sign to me. It could just mean it's
| a mature project.
| macintux wrote:
| Per jaltekruse it's inaccurate; work has moved repos.
|
| https://news.ycombinator.com/item?id=31457631
|
| I do tend to think that any web technology that isn't changing
| is dying. Browser, HTML, are admittedly both much more stable
| than they used to be, but the world keeps moving.
|
| (Edit: fixed spelling of @jaltekruse)
| [deleted]
| hprotagonist wrote:
| A source block type would have been a very natural fit, it's
| surprising that isn't how they chose to go.
| ```equation e^{i\pi}+1\eq0 ```
|
| feels like what i'd try to do right off the bat.
| darkscape wrote:
| Yes, could use different tags for literal display and rendering
| eg ```tex and ```eq.
| ajnin wrote:
| A code block is used to display text literally, except adding
| syntax coloring. You would use it to display TeX source
| notation for example. A math block transforms TeX into
| something else, it's entirely different. I think it's correct
| that they did not use the code block syntax for this.
| edflsafoiewq wrote:
| It's how Github already handles Mermaid diagrams, so there's
| precedent, although you're correct that logically there
| should be a distinction between "display highlighted Mermaid
| source" and "render Mermaid diagram".
| Hendrikto wrote:
| Especially since this approach has already been tried and
| proven by competitors like GitLab.
| ly wrote:
| I prefer the $ $ way, as it makes it possible to do inline
| equations, while keeping the source easily readable.
| hprotagonist wrote:
| you can do both, the normal markdown way:
| `$a$` squared is `$a^2$`, which is good to know for the
| pythagorean theorem: ```equation a^2+b^2\eq c^2
| ```
| ly wrote:
| Ah yes, agreed, then that does indeed seem like to optimal
| solution here.
| [deleted]
| IshKebab wrote:
| That doesn't work because then how do you display $a$ as
| literal inline code?
| runarberg wrote:
| What about: Inline code is ` $a$ `
| automatically trimmed
|
| But I think $`a+b`$ makes more sense (or even $$a+b$$; I
| mean this is markdown after all, not LaTeX).
| JadeNB wrote:
| > But I think $`a+b`$ makes more sense (or even $$a+b$$;
| I mean this is markdown after all, not LaTeX).
|
| True, but it _is_ TeX notation, and `$$ $$` for inline
| math goes deeply against the experienced TeXnician 's
| intuition. Why intentionally use notation that violates
| some users' domain intuition when there's an alternative
| that's no worse?
| samwillis wrote:
| They suggest this for inline using combination of the code
| back tick and dollar syntaxes:
|
| Inline math: $`a^2 + b^2 = c^2`$.
| jaltekruse wrote:
| One thing that the article gets wrong is accusing mathjax of
| being abandoned. Development has moved to a new repo for the next
| version.
|
| https://github.com/mathjax/MathJax-src/graphs/contributors
| [deleted]
| thaumasiotes wrote:
| > advantages of KaTeX:
|
| > It's faster.
|
| > You can copy-and-paste math.
|
| Someone mentioned that you can theoretically copy-and-paste KaTeX
| output in an earlier thread about GitHub's new math rendering
| too. But I think calling that an "advantage" is crazy.
|
| LaTeX will transform your one-dimensional textual formula
| specification into a two-dimensional graphical formula. The
| concept of copying and pasting the output as text is a category
| error. It isn't text and if you try to paste it, you'll get
| something other than what you wanted.
|
| Just to be sure I'm not crazy, I tried copying the output of the
| demo on the KaTeX homepage. Here it is:
|
| > f(x)=[?]-[?][?]f^(x) e2pixx dx
|
| This is much, much, much worse, if you want a textual
| representation, than copying the LaTeX source:
| \f\relax{x} = \int_{-\infty}^\infty \f\hat\xi\,e^{2
| \pi i \xi x} \,d\xi
|
| And it's worse even though the raw source includes the quirk that
| LaTeX isn't able to provide proper spacing for the differential
| over which an integral is being calculated, so you have to space
| it yourself with \, commands.
| JadeNB wrote:
| > \f\relax{x}
|
| I know it's not your point, and the design choice is KaTeX's,
| not yours, but making a macro that has to be invoked as
| `\f\relax{x}` to substitute for `f(x)` is ... kind of crazy.
|
| (Of course, in regular TeX, at least, you could do `\f\relax
| x`, saving one token at the expense of looking even less like a
| function invocation.)
| thaumasiotes wrote:
| `f(x)` works just fine. As far as I can see, the _entire_
| point of their \f macro is to let you write `\f\hat x`
| instead of `\hat{f}(x)`.
|
| Leaving aside whether that's a good idea, it's not at all
| clear why the example then goes on to use `\f\relax{x}` to
| display a function with no diacritic in its name. The
| diacritic was the only reason to use \f in the first place.
| And the advertised definition, `#1f(#2)`, doesn't only
| require \relax when you want to omit a diacritic. It also
| prevents you from doing perfectly normal things like `f\left(
| something-hairy \right)`.
| Royi wrote:
| KaTeX also supports only susbset of the features of MathJaX.
| Some of them are really important. While speed is great,
| missing basic features is the worse. I'm happy with GitHub's
| choice.
| runarberg wrote:
| The author fails to mention MathML as an alternative choice. The
| options aren't just MathJax and KaTeX, but also raw MathML.
| MathML gives you extremely fast rendering, more font choices,
| copy-paste, a11y, etc. out of the box. The only downside is that
| Chrome is lagging behind in implementation, for that they could
| use MathJaX as a polyfill--as MathJax understands and is able to
| transform MathML--and allow Safari and Firefox users the benefits
| of using browsers that can render math natively.
| forgotpwd16 wrote:
| It isn't mentioned because because they aren't really the same
| thing. MathML is a web native math markup language and being
| XML is meant to be written by machines rather humans[^0]. TeX
| is a markup language that MathJax and KaTeX render to a web
| suitable format but meant to be written by humans[^0]. Both
| MathJax and KaTeX have support for rendering TeX to MathML.
|
| [^0]: Compare Pythagorean theorem written in MathML and TeX.
|
| MathML: <math> <mrow><msup><mi> a
| </mi><mn>2</mn> </msup><mo>+ </mo><msup><mi>b
| </mi><mn>2</mn> </msup><mo>= </mo><msup><mi>c
| </mi><mn>2</mn> </msup></mrow></math>.
|
| TeX: $$ a^2 + b^2 = c^2 $$
|
| I'll be surprised if someone preferred to write the first
| rather the second.
| runarberg wrote:
| Nobody writes the first example by hand[^1]. They write it in
| TeX (or some other easy to write dialect, or use a graphic
| WYSIWYG editor) and then use a tool to translate it to
| MathML.
|
| What I'm advocating here is that GitHub translates TeX to
| MathML on their servers and serve us the MathML, as opposed
| to leaving the TeX as is and ship a JavaScript library to
| render it after it reaches our browsers. Chrome users won't
| see a difference as they don't support MathML, so they need
| MathJax as a polyfill. But there is a world of difference for
| us Firefox and Safari users.
|
| Another benefit is that you could allow us to include the
| pure MathML (by hand or authored by some other tool) if we
| preferred that.
|
| ^1: and if they did write it by hand it would be written as
| <math display="block"> <msup>
| <mi>a</mi> <mn>2</mn> </msup>
| <mo>+</mo> <msup> <mi>b</mi>
| <mn>2</mn> </msup> <mo>=</mo>
| <msup> <mi>c</mi> <mn>2</mn>
| </msup> </math>
| forgotpwd16 wrote:
| >What I'm advocating here is that GitHub translates TeX to
| MathML on their servers and serve us the MathML
|
| I see. What confused me was the "options aren't just
| MathJax and KaTeX, but also raw MathML" since those tools
| can be used server-side and they output some HTML or MathML
| or images. MathJax moreover besides TeX also takes MathML
| and AsciiMath input.
|
| >Another benefit is that you could allow us to include the
| pure MathML
|
| I guess they went with what most people work with since
| rendering TeX in Markdown complements their Jupyter
| notebook rendering.
|
| >and if they did write it by hand it would be written as
|
| Maybe. I copied my example from MDN docs git repo.
| zitterbewegung wrote:
| The way to really solve this is unfortunately for every equation
| that you have on Github you need to generate a png for each
| equation and just insert it into the file until Github fixes the
| various issues.
| atomashevic wrote:
| I completely agree with the conclusions, GitHub repositories can
| really be the focal point of scientific publishing in years to
| come.
|
| I always wondered why it took so long to implement math. There
| are better implementations out there for sure, it's weird they
| waited for so long and implemented something that is below the
| standard of alternatives.
|
| The next step is to render citations from .bib files. I hope they
| get that right in the future.
| nmalaguti wrote:
| My theory is that there's already a lot of existing content using
| $ and $$ that GitHub wants to start rendering without requiring
| any changes.
|
| I agree the code block approach would be less ambiguous, but
| there is an advantage in going where people already are.
| runarberg wrote:
| The pick of $ and $$ as delimiters seems rushed, to be frank.
| Although I'm not a big fan of mixing LaTeX in Markdown, I
| understand that choice (alternatively you could go with ascii-
| math like syntax which mixes way better with Markdown IMO). But
| $ and $$ makes not a lot of sense other then LaTeX does it this
| way. It would have been easy e.g. to use $$ for inline math and
| $$$ + newline or ```math for block, and that would have gotten
| rid of many of the warts of mixing Markdown and LaTeX.
|
| In my opinion the familiarity of $ and $$ is sacrificing a lot
| for not much benefit.
| auggierose wrote:
| Given that the main point of using LaTeX in Markdown is
| familiarity of users, using $ and $$ is actually the ONLY
| proper choice. But yeah, it leads to problems, which is why I
| would not use Markdown in the first place, but some Markdown
| inspired format which mixes better with $ and $$.
| nvrspyx wrote:
| This is why I prefer AsciiDoc. It's consistent because
| there's only one implementation, it's less ambiguous, and
| more predictable. Although it takes a bit longer to
| remember all the syntax, it's not difficult, especially if
| you're only going to use the same subset of features that
| markdown supports since it supports most of the markdown
| syntax as well. I also much prefer the flexibility with
| tables compared to markdown. I just wish there were more
| parsers/converters other than the main ruby one and the
| transpiled JS one, although I know there's work being done
| on other language implementations.
|
| As an example for math/equations, inline math is
| stem:[sqrt(4)], which defaults to AciiMath, but can be
| changed with a page attribute. To specify inline, LaTeX is
| latexmath:[\sqrt(2)] and AciiMath is asciimath:[sqrt(2)].
|
| For blocks (which you can replace stem with either
| latexmath or asciimath to specify),
|
| [stem] ++++ sqrt(2) ++++
| edflsafoiewq wrote:
| Looks crazy verbose compared to $ and $$, especially if
| you're actually using it intensively.
| pxeger1 wrote:
| This does seem like a remarkably poor implementation, especially
| given the alternatives: GitLab, mentioned; StackExchange also has
| a pretty decent implementation; many markdown-based static site
| generators also have good support
| throwaway981572 wrote:
| I'm very happy they went with simple $..$ and $$.....$$
|
| This is much more natural for anyone doing math or science and
| also makes it easy to copy and paste math from elsewhere
|
| It's better that the parser works harder than to force an
| inconvenient syntax on the user.
| anonydsfsfs wrote:
| The problem with adding so much complexity to the parser is
| that it's now impossible to predict how any given Markdown is
| going to render on Github. If Github's parser was open-source,
| you could at least look at the source to figure out this stuff
| is handled, but it isn't, so the only alternative is tedious
| experimentation.
|
| One of the main draws of Markdown was that it was so simple you
| were rarely left guessing how any given input would be handled
| (though the lack of standardization hampered that).
| colejohnson66 wrote:
| It's simplicity is also it's crutch. It lacks so many niche
| things (like math) that every implementation have their own
| syntax.
| IshKebab wrote:
| The problem with heuristic parsers is that you can't learn the
| rules, so the only way to use it now is with live preview.
| cratermoon wrote:
| Do \left and \right work for parens?
| patrick451 wrote:
| > The reason why I'm so excited about this feature is that, in
| combination with version control and the issues/discussions
| capabilities in GitHub, I can see tectonic changes in how we're
| publishing science. At last, science can really reap the benefits
| of a connected internet by moving away from static PDFs to
| living, breathing repositories which render like PDFs and provide
| a central place where one can actually talk about the article. -
| And fix bugs!
|
| I'm skeptical of this take. Gitlab has had math rendering support
| for quite a while now, so this is hardly novel and doesn't seem
| to have resulted in the utopia the author is hoping for.
| Beldin wrote:
| I had the same feeling for a different reason: I don't think
| this reduces friction enough compared to sharing LaTeX files
| (on github or overleaf), which we can already do. So I don't
| think this will usher in a new era.
|
| I realise this could very well become the next "dropbox
| comment" - and I'll be happy to be proven wrong.
| patrick451 wrote:
| It would be cool if they would just render entire latex
| manuscripts that are part of the repo. It sort of sucks that
| you need to duplicate what you wrote a paper submission into
| markdown to get github to render it.
| rectang wrote:
| Did Github ever solicit feedback from the community for this
| feature? Was there ever a beta before they rolled it out?
|
| Because some of these critiques really should have been dealt
| with beforehand and I'm concerned that we're now stuck with lousy
| defaults that they won't ever be able to change.
|
| The visual font size problem seems particularly disastrous:
|
| > _The math font is a really small,_
|
| > _MathJax's default font MJXTEX-I and GitHub's default text
| Helvetica have a different x-height /cap-height ratio._
|
| I don't understand how Github could launch this feature with this
| problem unaddressed. LaTeX isn't just about getting formulas
| right, it's about communicating ideas.
| edflsafoiewq wrote:
| Small font size seems the easiest to fix. Kerning seems worse
| since people will manually tweak spacing with \, etc, so you
| can't just change it whenever you want.
| rectang wrote:
| I agree that kerning is also a problem, and I also agree that
| it it can't practically be fixed.
|
| However, even if it's theoretically possible to change the
| font size, would Github ever do so? My impression is that as
| an organization they place a high value on interface
| stability. Very little about how I interact with the site has
| ever changed.
|
| I suppose that individual publishers might stick in a hack to
| increase the font size, but a bad default means that as a
| consumer, I'll be stuck looking at tiny math on Github for
| the vast majority of documents.
| enw wrote:
| > Very little about how I interact with the site has ever
| changed.
|
| GitHub tunes the UI all the time.
___________________________________________________________________
(page generated 2022-05-21 23:01 UTC)