7 ms·

markdown has a bunch of flaws - most egregious is that it lacks a spec. GFM brings in a few nice QOL improvements and CommonMark tried to standardize - but it's

markdown has a bunch of flaws - most egregious is that it lacks a spec. GFM brings in a few nice QOL improvements and CommonMark tried to standardize - but it's very very soon that you run into it's warts - For ex - try to have a list which has a code block in it (or other complex content) For me, Asciidoc (and Asciidoctor) have become the default - formal spec, test cases and extension mechanism so that you don't have N + 1 flavors of it. It also has a markdown migration mode that eases moving from md. IMO, it is better in almost every way than markdown - the only reason it isn't as popular is that Markdown was made popular (and drove adoption) by the Github & others.

edraferi 7y ago
I evaluated several light markup languages a while back for use in technical contracts. Basically I was fed up dealing with MSFT Word’s formatting problems while iterating on complex content with internal and external lawyers. Asciidoc definitely seemed like the best option. The biggest thing for me was the ability to do complex numbered headers. Unfortunately the tooling wasn’t really good enough for my use case. I needed a clean way to move between Asciidoc and Word, and it wasn’t really possible. Pandoc claimed support for both Asciidoc and word, but it was only partial and couldn’t round-Trip the document. I considered developing & contributing the functionality, but I didn’t know the language the tool was written in and couldn’t justify investing more time in the experiment. Maybe it’s time to review the tooling situation and take another crack at it...
- rraghur 7y ago
  I've found decent results with .adoc --(asciidoctor)--> docbook --(pandoc)--> docx It won't roundtrip (and I doubt anything will ever) but I usually go only one way - converting to docx in the last stage.
geraldbauer 7y ago
So how is: .Ordered . number . number .. letter .. letter better and more readable than 1. number 2. number a. letter b. letter For sure Markdown has some cruft but isn't it better to improve Markdown itself than to try to "establish" a completly new format with some weird conventions such as: Level 3 Heading ^^^^^^^ Level 4 Heading +++++++++++++++ Why? ^^ or ++ is this in any way intuitive or an established convention that is so much better? PS: See Text with Instructions (.texti) for a (better) Markdown evolved variant / flavor :-) - https://texti.github.io https://texti.github.io
- TuringTest 7y ago
  > So how is (X) better? For sure Markdown has some cruft but isn't it better to improve Markdown itself than to try to "establish" a completly new format > PS: See Text with Instructions (.texti) for a (better) Markdown evolved variant / flavor You have answered yourself: markdown is not a language that can be improved, it's a mashup of several different slightly incompatible implementations, much like HTML in the early web during browser wars. You could try to create a standard body that defined a homogeneous definition that everybody adheres to and which could be extended with new features. But by that time you'd be better served off by using asciidoc, which already did that job and which is actually based on Docbook, supporting all the features of that complete standard for book publishing.
  - geraldbauer 7y ago
    Sorry you are misreading and misstating what I said - markdown is a language and can of course be improved as many flavors / dialects / extensions and so on proof. Evolution is usually way better in finding conventions than your top-down Docbook in Ascii (Asciidoc) flavor. Again (re)read the post above and tell me how the Asciidoc ordered list using . and .. is more readable or the heading level 3 or 4 using ^^ or ++ and so on.
    - rraghur 7y ago
      > post above and tell me how the Asciidoc ordered list using . and .. is more readable It isn't - the point is that asciidoc has a 'spec' whereas markdown has dialects because it's not rigourously specified (core or extensions). Which one you might run into is the luck of the draw. Should you try to improve markdown (and lots of people have), you end up with the N+1 standards problem (famous xkcd cartoon) and further fragmenting the implementation if at all it takes off. Getting one 'Markdown' that has features (and extensions) that work properly wherever you go isn't a technical problem . It's a problem created by the lack of a spec in the first place and IMO pretty much unsolvable now.
- GhostVII 7y ago
  The first example is nice because you don't have to change all of the numbers around every time you add/remove an entry from the list. But I don't like having to put the ".Ordered" before every ordered list, and in Markdown I think it will automatically make the numbering sequential if the source isn't anyways.
a-nikolaev 7y ago
Agreed. Writing lecture notes [1] in Asciidoc was a real pleasure. The clarity of specs and convenience beats Markdown in every way. It even beats TeX, I'd say, unless you want real control of the typography. A very nice default styling in Asciidoctor is a big plus for me too. [1] for example, this: https://a-nikolaev.github.io/fp/lec/2/ https://a-nikolaev.github.io/fp/lec/2/
- 616c 7y ago
  Impressive, direct, and clear enough is the FP book you cited I will likely give OCaml a go again, not just AsciiDoc, thanks!
  - a-nikolaev 7y ago
    Cool, thanks!
breck 7y ago
Great references and description of the field. If anyone wants to submit a pull request to the Dumbdown grammar, I would love one that adds links to all the great languages in this space, like markdown and asciidoc. Something like: link http://asciidoc.org/ AsciiDoc

edraferi 7y ago

I evaluated several light markup languages a while back for use in technical contracts. Basically I was fed up dealing with MSFT Word’s formatting problems while iterating on complex content with internal and external lawyers. Asciidoc definitely seemed like the best option. The biggest thing for me was the ability to do complex numbered headers. Unfortunately the tooling wasn’t really good enough for my use case. I needed a clean way to move between Asciidoc and Word, and it wasn’t really possible. Pandoc claimed support for both Asciidoc and word, but it was only partial and couldn’t round-Trip the document. I considered developing & contributing the functionality, but I didn’t know the language the tool was written in and couldn’t justify investing more time in the experiment. Maybe it’s time to review the tooling situation and take another crack at it...

rraghur 7y ago
I've found decent results with .adoc --(asciidoctor)--> docbook --(pandoc)--> docx It won't roundtrip (and I doubt anything will ever) but I usually go only one way - converting to docx in the last stage.

geraldbauer 7y ago

So how is: .Ordered . number . number .. letter .. letter better and more readable than 1. number 2. number a. letter b. letter For sure Markdown has some cruft but isn't it better to improve Markdown itself than to try to "establish" a completly new format with some weird conventions such as: Level 3 Heading ^^^^^^^ Level 4 Heading +++++++++++++++ Why? ^^ or ++ is this in any way intuitive or an established convention that is so much better? PS: See Text with Instructions (.texti) for a (better) Markdown evolved variant / flavor :-) - https://texti.github.io https://texti.github.io

TuringTest 7y ago
> So how is (X) better? For sure Markdown has some cruft but isn't it better to improve Markdown itself than to try to "establish" a completly new format > PS: See Text with Instructions (.texti) for a (better) Markdown evolved variant / flavor You have answered yourself: markdown is not a language that can be improved, it's a mashup of several different slightly incompatible implementations, much like HTML in the early web during browser wars. You could try to create a standard body that defined a homogeneous definition that everybody adheres to and which could be extended with new features. But by that time you'd be better served off by using asciidoc, which already did that job and which is actually based on Docbook, supporting all the features of that complete standard for book publishing.
- geraldbauer 7y ago
  Sorry you are misreading and misstating what I said - markdown is a language and can of course be improved as many flavors / dialects / extensions and so on proof. Evolution is usually way better in finding conventions than your top-down Docbook in Ascii (Asciidoc) flavor. Again (re)read the post above and tell me how the Asciidoc ordered list using . and .. is more readable or the heading level 3 or 4 using ^^ or ++ and so on.
  - rraghur 7y ago
    > post above and tell me how the Asciidoc ordered list using . and .. is more readable It isn't - the point is that asciidoc has a 'spec' whereas markdown has dialects because it's not rigourously specified (core or extensions). Which one you might run into is the luck of the draw. Should you try to improve markdown (and lots of people have), you end up with the N+1 standards problem (famous xkcd cartoon) and further fragmenting the implementation if at all it takes off. Getting one 'Markdown' that has features (and extensions) that work properly wherever you go isn't a technical problem . It's a problem created by the lack of a spec in the first place and IMO pretty much unsolvable now.
GhostVII 7y ago
The first example is nice because you don't have to change all of the numbers around every time you add/remove an entry from the list. But I don't like having to put the ".Ordered" before every ordered list, and in Markdown I think it will automatically make the numbering sequential if the source isn't anyways.

a-nikolaev 7y ago

Agreed. Writing lecture notes [1] in Asciidoc was a real pleasure. The clarity of specs and convenience beats Markdown in every way. It even beats TeX, I'd say, unless you want real control of the typography. A very nice default styling in Asciidoctor is a big plus for me too. [1] for example, this: https://a-nikolaev.github.io/fp/lec/2/ https://a-nikolaev.github.io/fp/lec/2/

616c 7y ago
Impressive, direct, and clear enough is the FP book you cited I will likely give OCaml a go again, not just AsciiDoc, thanks!
- a-nikolaev 7y ago
  Cool, thanks!

breck 7y ago

Great references and description of the field. If anyone wants to submit a pull request to the Dumbdown grammar, I would love one that adds links to all the great languages in this space, like markdown and asciidoc. Something like: link http://asciidoc.org/ AsciiDoc