Djot: A light markup language by @jgm

Spec
23

The reason I joined this forum is Djot! :smile:

24

I only joined this forum to voice some of my issues regarding markdown and was delighted to learn about djot which fixes some of them. However, I have to agree with @vas on his main criticisms, especially regarding line breaks. I wholeheartedly agree on the “human-friendly” requirement for markdown / a potential successor of it and for this, hard-wrapping is a bane.

Lists, nested ones in particular, are a pain in markdown, but I think they got considerably better in djot. What I especially like is the symmetry: if you want text before or after a list, you need an empty line to separate it. Still, due to hard-wrapping compatibility, the annoying empty line remains.
As I see it, the problem stems from a conceptual difference that I claim to exist in the meaning of the word “paragraph” from the standpoint of writing and layouting:

  • From a writer’s perspective, it is “a self-contained unit of discourse in writing dealing with a particular point or idea.” (Taken from Wikipedia).
  • From a layout perspective, it is a junk of text with a line break at the end and sometimes a bit of indentation and spacing here and there.

As a result, most writers don’t conceptualize lists as breaking a paragraph but rather as part of it. However, this is exactly what HTML does due to it’s nature of being an instrument of layouting, which offers an obvious way to interpret and implement lists. However, this is against the intuition of the average user (or maybe only me) and even if it wasn’t it shouldn’t be if djot or markdown seek to be used not only for HTML but other targets such as *TeX as well.
Personally, I really like this idea of separating thoughts visually by surrounding it with empty lines. It would make sense to render

some idea
text before list
1. text
  more text
  1. nested
    1. even deeper
    back one level
    1. deeper again
  back two levels
2. finally a second item
text after list

next topic

basically as is. And yes, this is an example where we have a single thought span over multiple “paragraphs”…
This also relates to the “ambiguity” @jgm mentioned. It’s not an ambiguity if you decide on precedence. In my opinion, it should be treated as a paragraph followed by a list.
Here is a proposed simplified parsing rule set for producing HTML:

  • If the next line is empty (or white space only), the next action is probably to close a tag.
  • Otherwise check the indentation and close all tags on the stack that go deeper than this level.
    • If the thing in the line is compatible with the tag on the top of the stack add it. If a p tag is the top of the stack, add br in between.
    • Otherwise, close the tag on top of the stack and add a new tag corresponding to the added line. If the new object is normal text, encapsulate it using p.

Maybe GitHub markdown is already what we want in this regard. I have to admit, that I didn’t check how they do it. Edit 2: Maybe it would actually be better to let new lines separate p tags instead of br tags inside a p.

In defense of hard-breaks: Sometimes they are indeed useful. For example when you have formulas in normal text. But please not as default behavior. A reversal of the situation using the \ character would work fine in my opinion and may also be familiar to people from the C pre-processor or python, where it is used in precisely this meaning: This line break is not a line break.
Edit: I think that cpp adds the line breaks in the output, so my comment on the C pre-processor is not correct, but that doesn’t affect the point I made.

Another thing I never understood is the need for loose and tight lists.
Edit: In my opinion, breaks with the concept of the empty line as a separation between things.
In the following snippet, if I want the new line between A and B, I get a mixture of tight and loose lists although the list starting with C is formated in the same way, except that its second paragraph is another list rather than a piece of text.

text

1. A
  
  B

  1. C

    1. text
    2. text

    text
  2. text
2. text
3. text

text

I guess, that’s my 50 cents. Turned out longer than expected.