General LaTeX support sounds very scary, but what about KaTeX, would it be considered mature, maintained and stable enough for the Modelica specification to depend upon? License concerns?

Markdown would be handy, but then we would need to agree on some dialect, which needs to be stable and come with a maintained and generously licensed implementation. What are the options?

For our part, using something significantly different than what Dymola uses would be a showstopper.
We want our documentation annotation to be supported at least OpenModelica and Dymola.

We switch from LaTeX to markdown some years ago (relying on pandoc) for most usages to accomodate more people. LaTeX is astounding and I love it, but it is esoteric.

Markdown (any reasonably well spread dialect would do for my part) could a be a low common denominator. Aren't we writing in markdown right here?

Markdown is used for readme on git repositories, to write documentation with Sphinx increasingly often as a replacement for cumbersome reST, as well as many popular tools such as Notion or Obsidian.

There are diverse specifications of Markdown, with first “vanilla markdown”: https://daringfireball.net/projects/markdown/. As far as I am concern, required features include:

• title (with # syntax)

• italic (italic) and bold (bold)

• cross reference

• figure with caption

• math (latex like ; main issue: choose the delimiter consistantly with Dymola at least)

• possibly: tables (can be bothering)

The rest would be considered bonus.

For our part, using something significantly different than what Dymola uses would be a showstopper. We want our documentation annotation to be supported at least OpenModelica and Dymola.

We switch from LaTeX to markdown some years ago (relying on pandoc) for most usages to accomodate more people. LaTeX is astounding and I love it, but it is esoteric.

Markdown (any reasonably well spread dialect would do for my part) could a be a low common denominator. Aren't we writing in markdown right here?

Markdown is used for readme on git repositories, to write documentation with Sphinx increasingly often as a replacement for cumbersome reST, as well as many popular tools such as Notion or Obsidian.

There are diverse specifications of Markdown, with first “vanilla markdown”: https://daringfireball.net/projects/markdown/. As far as I am concern, required features include:

• title (with # syntax)
• italic (italic) and bold (bold)
• cross reference
• figure with caption
• math (latex like ; main issue: choose the delimiter consistantly with Dymola at least)
• possibly: tables (can be bothering)

The rest would be considered bonus.

Well said, totally agree!

We will have to investigate exactly what Markdown extensions Dymola uses ( @DagBruck ). As I see the main benefit it is quick and works for simple documentation - without having to use a specialized editor.

For LaTeX it is display math, e.g.,

$$
x=\sqrt(x)
$$

Not because LaTeX math is the easiest to read and write, but because there's no viable alternative.

To my knowledge Dymola supports the GitHub dialect of Markdown. (We haven't implemented it ourselves, but that is what the toolkit documentation says.)

Note that GitHub isn't good at documenting their Markdown.

The formal specification they link to is: https://github.github.com/gfm/ from 2019, and then Math was added in 2022 https://github.blog/news-insights/product-news/math-support-in-markdown/ with separate documentation https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

Test from blog:

When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

Note that the latter (directly copied from the blog!) doesn't work in GitHub, it should be $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

And two variants from doc:

The Cauchy-Schwarz Inequality
$$\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)$$

The Cauchy-Schwarz Inequality

Unfortunately Dymola 2025x only support display math, not inline math or math-language. On the other hand without the weird white-space issue for display math.

Conclusion: I would just specify GitHub flavored Markdown with display math; and hope that tools will be more consistent.

Inline math works in Dymola with the following syntaxe :

Inline equation → \\\\(W_{TH}=\\alpha S(T_1-T_2)\\\\)