Implement Latex math formulas in docgen

[a-mr]

Summary

We don't have a feature to type mathematical formulas in our markup language.

RST, Github Markdown, Pandoc Markdown all support the display of Latex formulas.

Description

For Markdown mode we can adopt the syntax shared by Github extension and Pandoc extension.

Inline $\sqrt{3x-1}+(1+x)^2$
Block:
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Inline $\sqrt{3x-1}+(1+x)^2$
Block:
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Need to implement syntax in parser (rst.nim) and output generation (rstgen.nim).

For HTML rendering I suggest to make implementation based on Katex as the easiest option (MathML is incomparably more difficult).

Alternatives

No response

Examples

No response

Backwards Compatibility

No response

Links

No response

[Araq]

The problem with LaTeX's syntax is that even though math formulas are in a hidden tree structure (AST) LaTeX's representation is not an AST. It's unnecessarily losing information and is overly concerned with rendering aspects, quite ironically.

[a-mr]

The problem with LaTeX's syntax is that even though math formulas are in a hidden tree structure (AST) LaTeX's representation is not an AST. It's unnecessarily losing information is overly concerned with rendering aspects, quite ironically.

The explicit hierarchical representation is great only for specific purposes like efficient parsing or programmatical tree modification. For text editing of formulas it just should be concise and hence readable, and Latex is good at it.
And hierarchical essence is well reconstructed by human brain when one looks on the rendered formula, no need to reproduce that in text.
The math community has been using Tex/Latex for decades, and doesn't complain about its math syntax.

[Araq]

For text editing of formulas it just should be concise and hence readable, and Latex is good at it.

There is nothing particularly readable about Latex's syntax and I don't even want to know how many bugs it caused in published papers.

The math community is happier with Mathematica which keeps the tree structure.

[WangWei90]

How to write Mathematica expression in some text file(e.g. sth.txt or sth.tex) and compile-render it in PDF.

[a-mr]

The math community is happier with Mathematica which keeps the tree structure.

There is no ready to use renderer for Mathematica formulas.
And Latex is a de facto standard.

Your comments are valid but they don't propose a meaningful strategy.

The situation is similar to the choice of Markdown as default language. W.r.t. e.g. HTML both RST and Markdown do not manifest explicit tree structure in many parts, but Markdown is even worse:

• All its blocks (like bullet lists, etc) are allowed to not have additional indentation after the first line. Currently we do require additional indentation as per RST. Though the question if we need to implement this for compliance with Markdown standards?
  • even if there is indentation, different number of spaces mean different thing
  • what's worse, in Markdown it's allowed to dedent already running block that entails a lot of potential bugs when e.g. if user forgot terminating ``` for a code block even if the code block was itself indented
• Headings are allowed to "jump" through levels, e.g. 3rd level heading ### can follow 1st level one #. Of course in both RST and Markdown there is no section terminator syntax, but the RST requirement for section levels to be able to decrease only by 1 make the hierarchy implicitly present.
• Inline formatting in Markdown is required to treat the special symbols laxly. E.g. if for * there is nor finishing pair *, then not consider them as a start of emphasized inline spans, just a literal *. Yes, it leads to a lot of bugs, though some users ask us to implement it like in discussion around nim doc crashes when processing comment with an asterisk #19607 . While RST at least has implicit tree structure by requiring to finish special symbols.

But there are no well-established alternatives to Markdown, so it's OK to adopt some of these things that have some use or are familiar to use. Nim project is not required to solve all the problems of programming world.

Alternatives may become ready only in long time like 20 years, then only then there will be the time to switch to them.

[Araq]

Whatever syntax we implement should map easily to MathML. It can be a clean subset of LaTeX or it can be the full thing if there is a reasonably complete list of its quirks somewhere.