notes-computer-lightweightMarkupLanguages

From time to time i look into lightweight markup languages. These are not 'interesting' per se to me, but they are a very useful convenience. Imo lightweight markup is a key UI feature of wikis. I've also written my own lightweight markup that compiles to LaTeX? for writing math in (EasyLatex?).

A problem is that, at least in the past, there has been no single markup language that dominated, and often the existing markup languages didn't support all desired features, so each wiki implmentation and everything else ended up inventing their own.

However, now Markdown and ReST? seem to be popular, Textile also somewhat, and Creole is at least some sort of standard.

The problem with markdown is its creator has not responded to calls for standardized modificions to it, so it has splintered. The main contenders seem to be CommonMark?, MultiMarkdown?, Markdown Extra, and Pandoc Markdown.

" Markdown Extensions

Unlike reStructuredText, which is virtually identical across all its implementations, there are a wide variety of semi-compatible Markdown extension styles; the most popular are MultiMarkdown? and Markdown Extra (the latter implemented by PHP Markdown and Maruku, and partially by Python Markdown and Redcarpet); Pandoc has its own set of Markdown extensions, based on both Markdown Extra and reStructuredText; these Markdown extensions are the most similar to reStructuredText, while the Markdown Extra extensions have a smaller overlap, and the MultiMarkdown? extensions are only compatible with reStructuredText when they are also identical to parts of Markdown Extra. " -- https://gist.github.com/dupuy/1855764

https://github.com/jgm/CommonMark/wiki/Markdown-Flavors

in addition i occasionally see people extolling the virtues of ASCIIDoc, e.g. https://plus.google.com/114112334290393746697/posts/CdXJt6hVn5A , e.g. http://stackoverflow.com/a/908315/171761

This guy liked Creole: https://kcode.de/wordpress/1316-markup-languages

So i'd say the ones to consider currently are Markdown (with some extension, not sure which one), Creole, reStructuredText, ASCIIDoc. After reading some more about the cons of reStructuredText, i'm going to eliminate it as the syntax is too non-intuitive. Leaving Markdown, Creole, ASCIIDoc.

Note that Pandoc is a popular library for lightweight markup conversion, and this popularity means that some weight should be given to what is easy to make work with Pandoc. It seems like Pandoc prefers its extension of Markdown. Pandoc's extension of Markdown includes math. http://jekyllrb.com/docs/plugins/ lists a Pandoc plugin for the popular Jekyll static site generator.

Which of these can display the following math constructs: (a) matrices, (b) systems of equations aligned to the =s sign, (c) definitions by cases? Which of them are extensible to cover things like that (regardless of whether or not they already have those particular things) (i guess if you want true extensibility you end up with TeX?, but here i'll settle for just having blocks of text that are marked to be interpreted with a particular extension)?

Markdown

Pros:

Cons:

Intended use case: comments on blogs, etc

Links regarding pros and cons:

Links regarding extensions and standardization efforts:

Main site:

reStructuredText

Cons: some syntax is non-intuitive

Spec: yes

Intended use case: documentation within source code

Links regarding pros and cons:

Main site:

Quickref:

ASCIIDoc

Cons: unpopular

Intended use case: writing books, etc

Links regarding pros and cons:

Main site:

Apparently ASCIIDoctor supports MathJax?: https://github.com/asciidoctor/asciidoctor/issues/492

Creole

Cons: unpopular

Spec: yes

Intended use case: wiki pages

Links regarding pros and cons:

Main site:

HTML (not 'lightweight')

LaTeX and TeX (not 'lightweight')

DolDoc

http://www.templeos.org/Wb/Doc/DolDocOverview.html

some cool things:

markdeep

http://casual-effects.com/markdeep/

https://news.ycombinator.com/item?id=10402121

lines.love

line draw markup plaintext vector

http://akkartik.name/lines.html

other minimalist diagram formats: https://news.ycombinator.com/item?id=31638230

djot

https://github.com/jgm/djot https://djot.net/

"The repo owner, John McFarlane?, is the primary developer for PanDoc?. Having to wrestle with Markdown (and multiple flavors no less) led to him developing CommonMark? (which is some small tweaks from Markdown but with a spec!)." -- [2]

discussion:

General comments

There is a general tendency to write markup languages that are programming languagues or that can contain embedded code, eg TeX?, DolDoc?, various web framework templating languages. There are a few problems with having a Turing-complete markup language:

On the other hand, if you don't have any advanced features, then you can't do things like eg have a loop that renders every item in a list using a sub-template, and put the results into a rendered list.

But there are middle grounds between simple markup and Turing-completeness. Eg if you only have ifs and foreach loops, not while loops or gotos or other control flow constructs or cyclic data structures, you can't not halt.

" In the beginning was RUNOFF from MIT, which originally had about the power of Markdown. More features were added, and it became nroff, then troff, the ditrofff, and macro systems were added on top of it. It became too hard to use for casual work.

Then there was TeX?, which was a saner approach to what troff did. Macro systems were added on top of it. It became too hard to use for casual work.

Then there was HTML, which started out with about the power of Markdown. More features were added. It became too hard to use for casual work.

Then there was BBcode, which started out with about the power of original HTML. It didn't gain many features, and is still widely used.

Then there was Markdown, which started out with about the power of original HTML. More features were added. Macros have been added by at least five people, but haven't quite gone mainstream yet. When Markdown gets macros, it, too, will be too hard to use for casual work. " -- https://news.ycombinator.com/item?id=11016034

---

" bariumbitmap 6 hours ago

parent flag

I don't know of any light-weight markup language that are intentionally designed to be context-free and unambiguous. I wish I did.

I'm not sure if any exist, although some people have tried to write grammars for existing markup languages.

http://roopc.net/posts/2014/markdown-cfg/

https://github.com/asciidoctor/asciidoc-grammar-prototype

https://stackoverflow.com/questions/6178546/antlr-grammar-for-restructuredtext-rule-priorities

https://www.mediawiki.org/wiki/Markup_spec

" -- https://news.ycombinator.com/item?id=11168744

---

" I never understood this argument about rST. The syntax for the same MD features in rST is only /marginally/ different, certainly not harder. I use both, depending on the context (which forces me to use one or the other). Most of the time you don't even notice the difference, because both have a really good baseline.

However MD falls short for writing technical documentation, which is why pretty much anyone has to dope the "standard" (GH flavored MD, and so on). The syntax for the extensions is not any better than what rST offers. rST generally allows a more human-readable writing style, whereas MD with extensions has a lot of very verbose inline formatting.

In fact, rST CAN have a slight edge in my mind as a human readable document if you use the appropriate formatting, whereas MD with extensions is easier for a program to parse.

But, I repeat myself, for the same set of MD features, rST is hardly different. If you don't believe this, use pandoc and try to transform a vanilla MD document into rST.

Now pick any rST page from sphinx documentation, and move back to MD. Hardly any better. sphinx is often criticized for being "hard to write" or illegible, transferring the blame to rST, but for the same set of formatting MD is not better. sphinx allows a whole slew of extra features which require a lot of annotation, and MD doesn't save the day. ... " [3]

---

here's the formats that Github allows:

this page compares markdown, restructured text, mediawiki, asciidoc, org-mode:

this guy likes asciidoc over markdown:

the guy prefers restructuredtext or asciidoc to markdown:

this guy prefers restructuredtext to markdown:

Markdown and reStructuredText common subset

Why Asciidoc? http://asciidoctor.org/docs/what-is-asciidoc/

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356

In a few of the discussions, ppl complain that ReST? is too hard:

Similarly, there are a lot of comments that say, too bad, Markdown (the common core) simply does not support many needed features, hence the extensions, none of which (purportedly) are individually supported as well as ReST? or Asciidoc; and that ReST? is not that much harder.

There is some love for Asciidoc (and Asciidoctor), but mb just b/c it's the underdog?

Stackoverflow and Discourse use Markdown; Discourse also uses BBEdit

Standard Markdown was renamed CommonMark? b/c the Markdown guy didn't like the name Standard Markdown:

https://blog.codinghorror.com/standard-markdown-is-now-common-markdown/

GitHub? flavored markdown now has a spec. It is based on/an extension of CommonMark?. Apparently there is no formal grammar though, and making one would be difficult: https://news.ycombinator.com/item?id=13871781

https://githubengineering.com/a-formal-spec-for-github-markdown/

O'Reilly's Atlas uses Asciidoc: https://hackernoon.com/living-the-future-of-technical-writing-2f368bd0a272

Seems like everyone who likes Asciidoc likes Asciidoctor

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/74

These guys like asciidoc over ReST?:

This guy likes Markdown over Asciidoc:

This guy (on the Asciidoc forum) like Asciidoc over ReST?: https://groups.google.com/forum/#!topic/asciidoc/pwMi73QvCag

Markdown, Asciidoc, ReSt?: https://github.com/StringHead/Techniki-internetowe/blob/master/MarkDown,AsciiDoc,reStructuredText-comparison.rst

https://www.pydanny.com/markup-language-faceoff-lists.html

Hugo supports Markdown, but also Asciidoc and ReStructuredText? and org-mode [4]

readthedocs supports Markdown and RST [5]

https://www.smashingmagazine.com/2022/02/thoughts-on-markdown/

---

orgmode

and orgdown https://karl-voit.at/2021/11/27/orgdown/ https://lobste.rs/s/z1ruc5/orgdown_new_lightweight_markup_standard https://karl-voit.at/2017/09/23/orgmode-as-markup-only/ https://news.ycombinator.com/item?id=15321850

https://joseph8th.github.io/posts/wow-writing-literate-api-documentation-in-emacs-org-mode/

https://karl-voit.at/2017/09/23/orgmode-as-markup-only/ https://news.ycombinator.com/item?id=19622019

---

peatmoss 21 hours ago [-] ... I love org-mode, but wish that some of the features could be ported elsewhere just to make the format more ubiquitous. Or a stand-along org-mode notebook server. Or support in other text editors. Or...

reply

flukus 18 hours ago [-]

Do we want the format to be more ubiquitous? Org-mode is fantastic, but the format itself is .... obviously organic.

reply

peatmoss 17 hours ago [-]

So that I can use it everywhere and people won't look askance? Definitely!

If I compare RMarkdown and org-mode, for example, org is strictly better for academic writing or anywhere else where internal cross-references are needed. Org isn't an astounding format, but it is quietly competent.

reply

---

my annoyances with markdown

WikiCreole? seems to solve most of these, as does Asciidoc (neither solves: autolinking images; empty line before starting a list; # for comments; only WikiCreole? solves: local links with the same name).

So i guess i like Asciidoc better than Markdown. I've reviewed the pros/cons links regarding Asciidoctor above in this document, and it's still my favorite (vs Markdown).

My annoyances with Asciidoc are:

---

commonmark has a neat interactive tutorial:

http://commonmark.org/help/tutorial/

---

http://asciimath.org/

---

is there a regex parsable markdown-like thingee?

mb look at simplemark?

---

  1. orgmode #neovim #vim #norg #neorg

" Revise the org format - Simple, very extensible, unambiguous. Will make you feel right at home. Org and markdown have several flaws, but the most notable one is the requirement for complex parsers. I really advise educating yourself on just how bad markdown can get at times; what if we told you it's possible to eliminate those problems completely, all whilst keeping that familiar markdown feel?

Enter the .norg file format, whose base spec is almost complete. The cross between all the best things from org and the best things from markdown, revised and merged into one. " [6] https://github.com/vhyrro/neorg/blob/main/docs/NFF-0.1-spec.md

" I have written a parser for a subset of Org syntax, and I agree with the statement that Org syntax is complicated. As one example, let’s look at ways to make task lists. First, a headline can be marked as TODO. But plain lists can’t. Plain lists can be checkboxes, but headlines can’t.

These two concepts are very similar, but are separate. They don’t work well together. " [7]

---

http://users.rcn.com/david-moon/MMD/HTML/index.html

---

https://www.markdownguide.org/

---

myST is praised by [8] and implied to be better than markdown in a similar way that (in the author's opinion, at least implied; i have no opinion here) rST is better (https://en.wikipedia.org/wiki/ReStructuredText):

https://myst-parser.readthedocs.io/en/latest/

myST is an alternative language for Sphinx, the Python documentation generator tool that uses ReStructuredText?. It is a superset of CommonMark? Markdown.

---

https://github.com/spc476/mod_blog/blob/master/NOTES/testmsg -- [9] ---

my proposal

i've used UseMode? markup a lot, and markdown a little, and now i haz opinions. I'll write this section using my own proposal even though it is not being parsed that way


for diagrams

https://news.ycombinator.com/item?id=33704254

compare D2 with MermaidJS?, Graphviz, and PlantUML?: https://text-to-diagram.com.

---

https://pdx.su/blog/2023-02-05-asciidoc-and-markdown/ https://lobste.rs/s/vc8tmx/i_wish_asciidoc_was_more_popular

---