Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Math on GitHub: Following Up

nschloe.github.io

Post reply on HN
Print view View original

31–40 of 46 posts

Re: Math on GitHub: Following Up

#31

Post by chrismorgan »

rhn_mk1 wrote: post #27
chrismorgan wrote: post #21

Markdown is just generally awful because it’s not designed to be extensible. And so people make a total hash of things like this when trying to add custom inline syntax (because it’s not possible to do it compatibly), and abuse preformatted code blocks to do something other than show code. (Seriously, if you make ```mermaid … ``` turn it into a diagram, how am I supposed to show syntax-highlighted Mermaid code? Or ``…

Markdown is a dead end, and that's why I'm using it. There's only so much syntax you can put into plain text and remain readable more or less as text, as opposed to code. I, too, would prefer some other language for complex expressions, although that's to keep Markdown simple rather than to obtain power. I never want to decypher latex in READMEs I read, unless it's a readme for a latex library.

I’ve seen all kinds of awful README.md files because people are trying to shoehorn stuff into Markdown that doesn’t fit.

The problem with Markdown is that it isn’t simple; rather, it’s simplistic, and quite a few things that should be simple instead require terrible hacks to work around Markdown and use HTML.

reStructuredText is generally quite a bit better in this regard because it focuses on expressing semantics.

Re: Math on GitHub: Following Up

#32

Post by chrismorgan »

WorldMaker wrote: post #28
chrismorgan wrote: post #21

Markdown is just generally awful because it’s not designed to be extensible. And so people make a total hash of things like this when trying to add custom inline syntax (because it’s not possible to do it compatibly), and abuse preformatted code blocks to do something other than show code. (Seriously, if you make ```mermaid … ``` turn it into a diagram, how am I supposed to show syntax-highlighted Mermaid code? Or ``…

reStrutucturedText is still useful to look at for inspiration here. It had the concepts of extensible metadata ("field lists"), spans ("interpreted text"), and blocks ("directives"). Including things like applying metadata to spans (using essentially Footnotes to provide field lists to interpreted text sections, like but better than Markdown's reference style for hyperlinks which almost no one uses but were much more…

I’m very deeply familiar with reStructuredText, having bent both it and Sphinx to my will in great detail a decade ago.

A decade ago, I thought that maybe if reStructuredText had had a non-Python implementation (most significantly at the time, PHP and JavaScript) it would have conquered instead of Markdown, given how clearly superior it is.

Now, I’ve decided that the fact that reStructuredText wasn’t ported is actually bound up in the reason why it didn’t conquer: it’s too fancy, too complex. Markdown is an awful kludge that was built on regular expressions, duct tape and HTML and knows it’s unsound. It’s very strongly web-native. reStructuredText is beautiful elegance and perfection of form, but aggressively medium-neutral, painfully so when you only care about the web, and difficult to implement, and unforgiving of content errors.

So I still wish reStructuredText had won, but I can understand more clearly now why it didn’t, and in fact never really stood a chance.

Re: Math on GitHub: Following Up

#33

Post by infogulch »

simonw wrote: post #25

Just spotted this on the GitHub blog, posted 33 minutes ago: https://github.blog/changelog/2022-06-28-fenced-block-syntax... > Users can now delineate mathematical expressions using ```math fenced code block syntax in addition to the already supported delimiters.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run the contents as X and render the output in the document".

Re: Math on GitHub: Following Up

#34

Post by rustyminnow »

infogulch wrote: post #33
simonw wrote: post #25

Just spotted this on the GitHub blog, posted 33 minutes ago: https://github.blog/changelog/2022-06-28-fenced-block-syntax... > Users can now delineate mathematical expressions using ```math fenced code block syntax in addition to the already supported delimiters.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run…

I was confused about your comment at first - I was sure it was already a feature where you could use ```X to render the contents with a language. E.g. you could go ```java or ```javascript and get syntax highlighting for that language.

What you're saying is since ```mermaid now renders a mermaid diagram, there isn't a way to display a block of raw mermaid code with syntax highlighting.

That's a very valid point.

Re: Math on GitHub: Following Up

#35

Post by whatshisface »

rustyminnow wrote: post #34
infogulch wrote: post #33

Earlier quoted context omitted.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run…

I was confused about your comment at first - I was sure it was already a feature where you could use ```X to render the contents with a language. E.g. you could go ```java or ```javascript and get syntax highlighting for that language. What you're saying is since ```mermaid now renders a mermaid diagram, there isn't a way to display a block of raw mermaid code with syntax highlighting. That's a very valid point.

They could add a ```mermaid-source tag.

Re: Math on GitHub: Following Up

#36

Post by infogulch »

rustyminnow wrote: post #34
infogulch wrote: post #33

Earlier quoted context omitted.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run…

I was confused about your comment at first - I was sure it was already a feature where you could use ```X to render the contents with a language. E.g. you could go ```java or ```javascript and get syntax highlighting for that language. What you're saying is since ```mermaid now renders a mermaid diagram, there isn't a way to display a block of raw mermaid code with syntax highlighting. That's a very valid point.

I agree my comment was difficult to understand, so I edited it to hopefully make it better. Thank you!

Re: Math on GitHub: Following Up

#37

Post by thangalin »

infogulch wrote: post #33
simonw wrote: post #25

Just spotted this on the GitHub blog, posted 33 minutes ago: https://github.blog/changelog/2022-06-28-fenced-block-syntax... > Users can now delineate mathematical expressions using ```math fenced code block syntax in addition to the already supported delimiters.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run…

KeenWrite[1] uses a "diagram-" prefix for text-based diagrams[2]. What's needed is a standards body for Markdown[3]. GitHub should not be imposing de facto standards.

[1]: https://github.com/DaveJarvis/keenwrite

[2]: https://kroki.io/

[3]: https://talk.commonmark.org/

Re: Math on GitHub: Following Up

#38

Post by ratmice »

infogulch wrote: post #33
simonw wrote: post #25

Just spotted this on the GitHub blog, posted 33 minutes ago: https://github.blog/changelog/2022-06-28-fenced-block-syntax... > Users can now delineate mathematical expressions using ```math fenced code block syntax in addition to the already supported delimiters.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run…

The simple fix for this is that you should use "```math render" or some such, the language is specified as the first word with everything after the space up to the newline currently ignored...

Re: Math on GitHub: Following Up

#39

Post by infogulch »

ratmice wrote: post #38
infogulch wrote: post #33

Earlier quoted context omitted.

I really don't like overloading ```X as a way to render the output of running the code, because now you have no way to display a block of raw mermaid or math code which is the whole point of ``` in the first place. I would be much happier if they introduced a syntax variation to enable this feature more generally instead of overloading the purpose of backticks, something like ```!X (```!math or ```!mermaid) for "run…

The simple fix for this is that you should use "```math render" or some such, the language is specified as the first word with everything after the space up to the newline currently ignored...

> everything after the space up to the newline currently ignored

Oh I didn't know that, that's perfect!

Re: Math on GitHub: Following Up

#40

Post by woodruffw »

bachmeier wrote: post #17
woodruffw wrote: post #15

Earlier quoted context omitted.

> Handle the math sections first and make math support opt-in. Unless I'm misunderstanding what you mean, this isn't possible in a backwards-compatible manner: It's perfectly reasonable for pre-existing Markdown to have content like "Bob pays $1 for bananas, Susan pays $2," which would mis-render a normal sentence as if it had inline math content. The blog post author's proposal is the most reasonable one: it's both…

> which would mis-render a normal sentence as if it had inline math content Not if it's opt-in. If you opt in to math support, you use \$, but that's a choice you make. Also, you can force an opt-in to use dollar signs vs \[ and \(. > The blog post author's proposal is the most reasonable one I gave the problem with that. It's not standard syntax, so markdown parsers like Pandoc stop working. And technically, that do…

> Not if it's opt-in. If you opt in to math support, you use \$, but that's a choice you make. Also, you can force an opt-in to use dollar signs vs \[ and \(.

How would you make it opt-in? With a pragma at the beginning of the markdown file? I don't mean that as a rhetorical question; good UX for these kinds of things is hard.

> I gave the problem with that. It's not standard syntax, so markdown parsers like Pandoc stop working. And technically, that doesn't even fix anything, because someone could have been using that syntax already. It might not be common, but it isn't a foolproof fix.

I think the cat is already well out of the bag with that: GitHub has supported triple-tick with the "geojson" and "topojson" tags for quite some time, choosing to render them as maps[1].

Renderers like Pandoc will handle the above gracefully by degrading to a code block, which is perfectly reasonable until they support it directly. In any case, there's precedent for it.

Edit: And it looks like they do support "```math" anyways[2]. It's just not well documented, and doesn't have an inline counterpart.

[1]: https://docs.github.com/en/get-started/writing-on-github/wor...

[2]: https://docs.github.com/en/get-started/writing-on-github/wor...

Post reply on HN