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.
Today: 4 Add.

[DagBruck]

Ok, good enough.

[HansOlsson]

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

Today: 5 Add.

However, seems best to postpone until after 3.7.

[HansOlsson]

An option might be to list the features (heading, bold, link, display math, ...) to be supported. To be discussed further.

[henrikt-ma]

An option might be to list the features (heading, bold, link, display math, ...) to be supported. To be discussed further.

Unfortunately, the fundamental idea of most markdown languages that any input is valid input makes this more difficult than it first might seem. Since there is no solid ground for rejecting something that looks like something outside of the supported feature list, the only thing a tool could do to follow the specification is to not give any special meaning to anything but the listed constructs, but I am afraid that this could be hard to achieve with off-the-shelf markdown implementations.

For example, say we didn't include the "underscore syntax" for italics. Then this would still be valid input:

_This is not in italics._

expected to be rendered like this:

_This is not in italics._
but the problem is that probably no off-the-shelf implementation would render it so, and the user would get the wrong impression of using a supported feature.