Hacker News Reader

Comment by adlpz | Hacker News Reader

I understand the rationale and how CommonMark parsing is not trivial and could be simplified, but the resulting language misses, for me, the best part of Markdown: that it happens to be pretty much just what I'd write in plain text anyways.

The odd newline requirements on lists and blocks, the special syntax for raw HTML and so on makes Djot feel more artificial to me.

View on HN

The fact that we cannot standardize on extensions means that markdown feels inadequate for more technical documents. If just a free more restrictions means I can easily add block annotations to everything, I will jump aboard immediately. That it is easier for parser writers is just a perk.

I honestly don't get why Markdown became preferred in most projects over AsciiDoc.

Because people know and like Markdown. It’s good enough so they don’t go looking for a replacement.

Markdown is used enough that you are going to need to know the syntax. So a competitor doesn’t just have to better, it has to have enough additional merits to be worth learning in addition to Markdown.

AsciiDoctor and Org Mode both have substantial additional merits over Markdown, and have dedicated user bases. The problem nowadays is that of implementation availability.

Have you tried to parse it? Even the Swiss army knife of document formats, pandoc, only supports it as an output format.

I suspect a lot of it's inertia from before the choice mattered or was actually reflected on (though I guess there are still plenty of projects changing).

It's easy, most projects can satisfice with it, and people on the projects that can't satisfice with it may not think about markup enough to realize they're painting themselves into a corner until they have a big ballast of existing documentation to cope with?

I've been fumbling around for how to convey signs that a project may need better tools (https://t-ravis.com/post/doc/what_color_is_your_markup/) but it's been slow-going and I'm bearish on how well ~better-practices will spread.

I think this is partly because AsciiDoc has broadly been tied to a single implementation, AsciiDoctor, without a spec, not even a sketch in a blog post like the original Markdown was. It's only recently that AsciiDoc has begun to think of itself as "a markup language" rather than "the markup language used by AsciiDoctor". A spec is apparently WIP.

As for why it never gained the memetic popularity of Markdown that might have led to a different trajectory, that's harder to say. The One True Markdown is fundamentally much simpler than AsciiDoc, and consequently much easier to learn, easier implement in JavaScript for live rendering on the Web, and easier to extend with your own opinionated features. So I think it was easy and attractive for various platforms like Hacker News and Github to support it, and this I think had a snowballing network effect.

Personally I love AsciiDoc and I think it's the future of technical writing and publishing. It's everything I wanted out of reStructuredText but without its fussy, non-composable syntax. However I don't think that future will become reality until a spec is published that is friendly to implementers other than AsciiDoctor.

AsciiDoctor is a second implementation that doesn't even fully compatibly implement the original specification. The original AsciiDoc is pretty well-specified, and it's mostly the plaintext markup of stuff that was intended to go to DocBook, with very little surprises from that.

AsciiDoctor pretty much focused on a direct HTML translation and ignored the inconvenient parts. (Some of the inconvenient parts are deprecated syntax that while AsciiDoc's had a replacement for, I've written the old style for ~20 years and when GitHub tries to render a document with AsciiDoctor, oops; sometimes I'll change the document, sometimes I'll decide rendering on GitHub isn't important.)

> I honestly don't get why Markdown became preferred in most projects over AsciiDoc.

I think the primary reason is because Markdown is prettier to read (and also secondarily because it's good enough).

There are lots of markup formats, but markdown is probably the easiest on the eyes.

I mean, you can already do all of this (and more) in Pandoc's Markdown dialect, which is CommonMark-compatible. The main things you're getting here are sanding down some of the sharp corners that CommonMark has, in exchange for some uglier syntax if you actually care about the use cases those sharp corners enable.

The point on standardization is sort of moot until Djot becomes big enough to be more than a single implementation. I'd be happy to see it get to that level, but I won't be waiting for it either since Pandoc Markdown is perfectly servicable as it is.

> The point on standardization is sort of moot until Djot becomes big enough to be more than a single implementation.

I'm currently working on a second implementation, mostly because I want my docs to be dependency-free, but also for standardization of djot.

Exactly, the sublist newline stuff is a total nonstarter for me. Sorry, I guess I'll run a markdown parser that takes an extra second or whatever to run.

If you just want the expressiveness of Markdown then that's fine, but this is targeted at the same space as AsciiDoc - writing big documents and even books. It's going to be painful doing that without the ability to add footnotes, cross references, figures, notes, etc. etc.

I mean you can do it - look at all the RFCs for example - but they must have been unpleasant to write and they're certainly unpleasant to read.

What odd newline requirements? I skimmed the syntax reference and couldn’t find any.

In markdown

    My favorite number is probably the number
    1. It's the smallest natural number that is
    > 0. With pencils, though, I prefer a
    # 2.

is a paragraph, a list item, a block quote, and a heading (4 things). In djot it's just a single paragraph.

If you want it to be 4 things you have to add a newline between each one.

Personally I think djot gets this right.

Ah, thanks. I agree that it makes sense to require an empty line before block elements that typically also require an empty line after.

Agreed with the exception that djot also applies this to nested lists, which I think is a huge misstep. User ergonomics are more important than convenient parsing, and while many markdown parsers interpret your example in an un-ergonomic way, djot rejects this:

    - foo
    - bar
        - baz
    - foobar

and demands this:

    - foo
    - bar

        - baz

    - foobar

which is an unergonomic choice.

This is so horrifying I did not believe you and had to go test to make sure. Jesus that's awful. Force a newline on me before a list? Ugh but fine. Force it for every sub bullet? No freaking way, that looks catastrophically bad.

This forcing new lines thing almost totally eliminates any desire I have to experiment with it, when I was very excited about it when I first saw it come up. Hopefully they'll change their mind. They want source code to be readable then make a decision that makes our eyes bleed.

This. The rationale of Djot's design decisions are sane. Heck, it's even understandable that lists 'require' the blank line. Yet blank lines in lists really break the reading flow. It would be worthwhile to sacrifice a pure design decision in favor of practicability and readability.

The motivation for this choice is not "convenient parsing" but deeper considerations of language design. As explained at https://github.com/jgm/djot#rationale , this choice follows from two desiderata: (1) "The syntax should compose uniformly, in the following sense: if a sequence of lines has a certain meaning outside a list item or block quote, it should have the same meaning inside it." (2) "The syntax should be friendly to hard-wrapping: hard-wrapping a paragraph should not lead to different interpretations, e.g. when a number followed by a period ends up at the beginning of a line." The document explains the compromise we made in commonmark to avoid the need for blank lines. Djot tries to be more principled.

Also preferring rST-style list syntax, requiring an empty line between parent and child lists.

So:

  - list
    - sublist
    - sublist

is valid Markdown but invalid djot, while

  - list
  
    - sublist
    - sublist

is valid djot.

I wonder how much of that is famliarity? I find Asciidoc to be much closer to what I would write, as well as being more full-featured. It's much worse for parsing than even CommonMark though.

Reply on news.ycombinator.com