Start adding markdown

[HansOlsson]

This is just intended as a starting point for the discussion.
Closes #3636

Unclear points:

• Compatibility? Should we reserve <...> for future extensions?
• Specification of GitHub flavored markdown (especially as they don't update their own documentation).
• Reference KaTeX as sub-set of LaTeX-math?
• More?

[maltelenz]

In my opinion we need to be more specific about the flavor. Github could change their implementation at any time, and what would that mean? The MLS should point to a well defined specification.

[HansOlsson]

In my opinion we need to be more specific about the flavor. Github could change their implementation at any time, and what would that mean? The MLS should point to a well defined specification.

We could say Version 0.29-gfm of https://github.github.com/gfm/ (note in particular the extensions; they are marked with "extension" in the table-of-contents) with display math using $$ ... $$.

Unfortunately I cannot find an updated specification for what they currently have implemented.

Note: The math was announced in 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

[HansOlsson]

With the reference I believe it is now ready for review.

I didn't reserve other tags (in addition to HTML) - the reason is that I don't know whether potential new formats would use tags or something else. In case it is something else I guess we could do something like annotation(Documentation(info=..., format="SomethingElse"));

[HansOlsson]

Investigate if markdown 0.29 (without GitHub flavor) works as well: Tables is the most important extension (strikethrough and task lists seem unimportant).

[HansOlsson]

Investigate if markdown 0.29 (without GitHub flavor) works as well: Tables is the most important extension (strikethrough and task lists seem unimportant).

Tables are so essential that it doesn't make sense to consider it without that; thus I think the current proposal is the simplest.

[HansOlsson]

Need more consensus, tool-vendors to check how easy.

[HansOlsson]

When using QT can use: https://doc.qt.io/qt-6/qtextdocument.html#setMarkdown

[gkurzbach]

I found https://stackoverflow.com/questions/39560644/what-library-does-github-use-for-parsing-markdown and it boils down to https://github.com/gjtorikian/commonmarker
it might be not easy to use this in tools.

[HansOlsson]

I found https://stackoverflow.com/questions/39560644/what-library-does-github-use-for-parsing-markdown and it boils down to https://github.com/gjtorikian/commonmarker it might be not easy to use this in tools.

Agreed for the latter point, and one cannot expect tools to use the exact same code as GitHub for a number of reasons; which means that we need to in some way reference a specification for it (and a code saying "we activate a number of extensions that aren't specified").

[HansOlsson]

Off-line poll:

It seems we have three options:

• Add the current part, with imperfections. 👍
• Reject having markdown (as markdown without math is problematic) 👎
• More discussion 👀

Select emojis among those three.

[HansOlsson]

Off-line poll:

It seems we have three options:

• Add the current part, with imperfections. 👍
• Reject having markdown (as markdown without math is problematic) 👎
• More discussion 👀

Select emojis among those three.

3 Add, 1 Reject, 6 More discussion. Seems that "more discussion" is needed.