Alternative syntax for numered list and tables?

[offray]

Hi all,

First post over here and long time Pandoc's user/admirer.

I really share Djot's design goals and recently I was talking about it and its shared design sensibilities with Microdown in the Pharo mailing list (4th message in this thread).

As Djot tries to learn the lessons from Markdown, while not being limited by its shortcomings and creating a less complex format/parsers, I wonder if maybe my suggestion is out of scope or its conflicting with the simplicity goal. Anyway, given that this is a new format, it may be open to changes about a couple of features that I find painful in Markdown/CommonMark: numbered list and tables. I'll elaborate further.

I find Markdown's numbering list counter intuitive when reading the code because, If the number is repeated, it will keep the counter increasing, and if a numbered list is going to increase the counter and non numeric symbol should be used -- let's say ~, or ¬, as *, -, + and all numbers are already taken by Markdown for (non-)numbered lists. Sometimes, I'm reading the source code of a Markdown file and seeing a number repeated or non-sequential is an oxymoronic "numeric" reminder that I should not care about the list numbers!

Tables are mostly a pain to write/read in plain text editors without smart edition support (like OrgMode/NeoVim). Something like AsciiDoc tables should be better or anything that allows multiline cell writing in plain text. I wonder if a syntax like that could be implemented in Djot using its conventions (see example below, but I don't know if this is Djotish enough, correct or if it would require look ahead parser implementations)

::: table [This would be the title]{table properties}
|===
|Column 1, header row |Column 2, header row

|Cell in column 1, row 2, with longer text
that spreads in a readable fashion in several source lines 

|Cell in column 2, row 2
|===
:::

Of course, dealing with Markdown pain points, while being familiar and simple to write/read is a delicate balance

[jgm]

I don't quite understand what your criticism is with numbered lists: maybe you could explain more fully what you think djot could do better?

Tables: asciidoc tables are optimized for writing, not reading, so that goes against the Markdown spirit. The advantage is that they are better suited for non-simple tables. We definitely need a more flexible table syntax in djot. One idea is to allow list tables. There are also ideas floating around in the commonmark discussion group for more flexible pipe tables.

[offray]

List tables could work or even better the Wikipedia syntax that you are proposing, as it doesn't use English words by default (something that, as a non-native English speaker I value a lot of your design choices, @jgm, regarding markup syntax).

What I don't like about Markdown numbered list, can be explained better with a code example:

1. This is first.
2. This is second.
3. This is third.
4. This is forth

creates the same result as:

1. This is first.
1. This is second.
2. This is third.
5. This is forth.

And that:

1. This is first.
9. This is second.
18. This is third.
57. This is forth.

All of them produce, when rendered:

1. This is first.
2. This is second.
3. This is third.
4. This is forth.

So, reading the source code is kind of a constant numeric reminder that numbers don't matter. I would like to point that with a non-numeric symbol. Something like:

~ This is first.

~ This is second.

~ This is third.

~ This is forth.

Should produce the same output as a numbered list started in 1 and followed by the next consecutive numbers (~ is just a place holder, as I don't know if it conflicts with sub-indexes like in H~2~O, but it seems it doesn't). and maybe something like:

~21 This is 21st.

~ This is 22nd.

~ This is 23rd.

should indicate a numbered list starting in a particular value.

[bpj]

I like the current/Markdown syntax/behavior, because you can both keep your items numbered while editing and insert new items/rearrange items between the existing ones and not renumber every item without upsetting the numbering in the rendered document. Things like

1. first
01. inserted later
001. used to be 4
2. second
02. also inserted later
3. third
5. fifth

are not rare while I'm editing. Pandoc IMO does the Right Thing rendering that as a straight 1–7 list.¹

As for markers without digits I often edit longish YAML lists, and the lack of numbering can make me disoriented. Perhaps not "globally" (as in doesn't matter) but certainly "locally". For the same reason I make all lists of some length numbered when writing prose.

Footnotes

1. BTW editors trying to correct list numbering like the GH web UI just did on me is annoying. I want to (re)number my lists as and when I want to! ↩

[offray]

For me, the auto-numbering of online editors (in my case HedgeDoc, despite of all its qualities) is annoying also and is the one creating most of the non-consistent numbering schemes I have found.

What I would like is an extra syntax to indicate, numbers doesn't matter in this list, they will be numbered consecutively upwards from the first one and on (similar to what Typst does with its numbered list starting with + syntax for numbered lists and - for non-numbered). So both preferences, yours and mine, could be used.

Of course, creating a proper balance between alternatives, while being similar enough to popular formats, without inflating a lot the features is tricky. I like the Djot's minimalist approach and hopefully some features regarding tables, numbering and checklist can be added without too much feature creep.

[clbarnes]

IMO, having multiple options of characters to prefix non-numbered lists is a waste of syntax - we don't need +, -, and * to do the same thing. To me, - is the natural non-numbered list syntax, because in most fonts, * is a high asterisk which doesn't really look like a bullet point (and is also already used for emphasis), and I've very rarely seen + used. I very much like typst's numbered/ non-numbered distinction. So I'd propose something like e.g.

1. first
+. second
+. third

automatically increments. It harms readability a bit, but no more so than 1. 1. 1. 1. does. People use light markup differently and allowing people to prioritise readability at the cost of managing their own numbering, or to prioritise ease of editing by using auto-increment, would add value without adding too much complexity. By having a distinct (but pretty clear) auto-increment syntax you also could remove the "surprising" behaviour of changing numbers which the author has explicitly written, and give the author the flexibility of starting numbered lists at numbers other than 1.

[stoicon]

Using +. also looks like the increment operator in programming languages (++i)

[bpj]

Well printed documents use different markers in nested lists. It helps keeping them visually distinct. However I seldom use different markers when writing Markdown for Pandoc because when I reformat by converting Md → Md with Pandoc they all become - anyway. Being able to choose list markers is one of the few advantages of HTML.

[Omikhleia]

For the reminder some Markdown flavors (incl. Pandoc with adequate option) support # instead of a digit for an ordered list enumerator (equivalent to 1).

Currently Djot mandates a space after the # for headings, so re-using it here followed by the delimiter, as #., #) etc. wouldn't cause an ambiguity. The would allow compatibility with such Markdown constructs, and does not forbid an extended syntax for specifying the start number and numbering style:

iv. Start at roman "iv."
#. Step 2 (= as "v.")
#. Step 3 (= as "vi.")