Implement (more of the) Markdown language

[sebasguts]

Maybe it would be a good Idea to use some Markdown format in AutoDoc descriptions and text. I'm mainly thinking about

• Text formating, i.e. bold, cursive, headlines, etc.
• Hyperlinks and references, this would include https://github.com/homalg-project/AutoDoc/issues/34
• Lists by *, +, -

Would that be desirable?

[fingolfin]

I think that would be nice. For simple things like bold & italics, this is easy enough. However, full support is quite a chunk of work... and bears the risk of a half-assed implementation: First off, if only a subset is implemented, then it must be explicitly documented which subset; secondly, be careful to not implement some syntax "almost, but not quite" like markdown. Not that it is particularly clear what "markdown" actually means! See also http://johnmacfarlane.net/babelmark2/faq.html

So I guess I am really asking for a full-fledged Markdown parser, and that is quite a bit of work...

Finally, it might then still be useful to come up with a few extensions (like github did, and virtually everybody else).

[mohamed-barakat]

I am also afraid it is too much work to get it "right".

[sebasguts]

A complete Markdown support is indeed too much work, and also a hard piece of work. Also, some features just don't make sense, escaping special characters for example. It would be possible to hijack some existing markdown converter, but they are not written in GAP, so one would obtain a python/perl/c++/.... module inside AutoDoc, which would not be desirable. Maybe I can just add the features mentioned above, without calling in Markdown, and then document those?

[fingolfin]

That sounds more reasonable, yeah. You could still mention that it is a strict subset of Markdown, though

[sebasguts]

Then I will do this. Some of my ideas are currently written down here: https://gist.github.com/sebasguts/3c5cdb61eeda0ee9e1f8 Feel free to modify, please.

[fingolfin]

BTW: CommonMark might be interesting in this context.

In particular, the CommonMark spec, which addresses many ambiguities in the MarkDown "standard" (which never was a real standard to begin with). We may wish to aim towards resolving ambiguities in a fashion compatible with CommonMark; this way, we could point people to the CommonMark spec if they need clarification on how AutoDoc works.

But of course we only implement a small subset of MarkDown / CommonMark for now.

[sebasguts]

CommonMark supplies a Markdown to HTML converter as a C library without external references. If it is possible to change HTML to XML/Gapdoc, we could add this converter as an optional kernel module to AutoDoc.

[fingolfin]

These days, there is https://github.com/commonmark/cmark which is a very nice C library implementing CommonMark, and making it relatively easy to write custom "renderers". They already include renderers for XML, HTML, LaTeX, man pages and CommonMark (for "cleanup" processing). Adding one that produces GAPDoc shouldn't be hard. Of course that'd add a binary dependency to AutoDoc, which is not that nice. But on the up side, we'd get many nice features for free, and fully confirming to Markdown / CommonMark.

OTOH, we'd still want to handle some of our own special AutoDoc commands in there; I think that's the main obstacle (although I don't think it's that hard to overcome... but I might be wrong)