Blank line between list items

[gzagatti]

In the norg spec on lists, I have noticed that in all examples the list items are contiguous. Is it possible to separate items with an empty line?

Sometimes items can be quite long and having an empty line between them can be visually useful. For instance, would the following list be a valid list?

1. this is the first item

2. this is second item, sometimes items are very long and an empty line between them can be a useful visual artifact.

3. hello world.

[vhyrro]

Hey! Unfortunately those would be 3 separate lists in that case. Our reasoning for it is that if we were to allow this you couldn't be able to easily determine how lists are separated. I mean take a look at this:

- I am a list item
- I am another list item

- I am now a separate list
- And another element of the separate list

Visually you wouldn't expect these to be the same list, right? It's why we've elected not to build our parser that way. The only workaround I can think of is using trailing modifiers to continue the flow of the line:

- I am a list item
- I am another list item~

- I am now still part of the original list item
- And another element of the same list

That causes the next line to be treated as part of the second list item, therefore joining the entire list together. It's not the most elegant in the world, but it's the only way I can think of doing it as of right now. The Neorg concealer can and will hide the ~ character automatically if it's configured correctly. I'm open to discussions about this but I feel that disallowing whitespace between list items is logical.

Also a small note:
1., 2. and 3. are not Neorg syntax :P

Neorg uses ~ to denote ordered lists, and the #ordered carryover tag to change the way ordered lists count. That stuff is explained in the spec if ya need more details.

Example:

~ I am an ordered list
~ I am another ordered list element

Instead of:

1. I am an ordered list
2. I am another ordered list element

[gzagatti]

Your answer is very helpful. I think that the trailing modifier is actually a good solution to the problem as it is not visually obstructive and provides a good guide to eyes.

~ this is the first item~

~ this is second item, sometimes items are very long and an empty line between them can be a useful visual artifact.~

~ hello world.~

However, I was left wondering what's the syntax for a multi-paragraph list item as I could not find this in the manual. Would it be correct to write like below (irrespective of the indentation)?

~ this is the first item~

~ this is second item, sometimes items are very long and an empty line between them can be a useful visual artifact.~

  this paragraph should be part of the second list item, irrespective of the indentation.~

  this is a continuation of the item in a third paragraph.~

~ hello world.~

A final note, I do think it would be a good idea to allow for the use of numbers in the plain text file for ordered list. One of the advantages of the syntax it that it can be read in plain text format and I do often only read the plain text file. As a compromise, what about the following syntax:

1~ box
2~ tiger
3~ hat

or

~1 box
~2 tiger
~3 hat

I think the first option looks more neat. The parser could then ignore the number during the rendering, but it would still be useful for the reader.

[mrossinek]

However, I was left wondering what's the syntax for a multi-paragraph list item as I could not find this in the manual. Would it be correct to write like below (irrespective of the indentation)?

This is currently in the works. See nvim-neorg/tree-sitter-norg#27

A final note, I do think it would be a good idea to allow for the use of numbers in the plain text file for ordered list.

We currently do not plan on supporting this as it breaks our existing syntax rules which we would like to abide by in order to keep the file format consistent and unambiguous. Maybe vhyrro has some more input on this though.

[gzagatti]

Thanks! I've commented on the draft proposal.

I think the detached modifier ~1 , ~2 , ... would not be such a big break with the syntax. The current definition of detached modifier is a character followed by whitespace. However TODO list items do not follow this pattern since they satisfy the following pattern - [ ], - [-], ... . So in a sense, the ordered list item composed of the character ~ followed by digits would be similar to a TODO item, except that here we use digits instead of bracketed expressions.

Again, my main motivation for allowing digits in the ordered syntax is for allowing the document to stand alone as much as possible as plain text. A reader would not be able to tell the index of an ordered item when reading the plain text file, even though this the main motivation for ordered lists.

[vhyrro]

Hey! Thanks for the idea, but we think that ~1 etc. is fundamentally flawed in many different aspects, so I'll try giving a very thorough answer here so you know why we're doing things the way we're doing things.

So, let's discuss - why wouldn't ~1 work?

• Modifier repetition. ~1 is actually comprised of two different characters here. In the case of a TODO item this is not the case: - makes up the detached modifier, whilst [-] is an extra segment of the detached modifier. If our syntax were -[-] only then would TODO lists not follow our pattern.
• Incorrect counting. How do we handle this?

  ~1 Hello
  ~3 World
  

  We are absolutely against "auto-numbering" like it occurs in markdown, where the element with number 3 is rendered as an item that's got a number 2, which it clearly doesn't.
• Readability vs usability. Although it may be easier to see at a glance at which number you're at it becomes a pain to manage from a writer's standpoint. If you were to reorder several items in a long list you now have to update every number in that list! And if the user isn't bothered to do so you'll end up with something like this:

  ~3 This is an item
  ~1 This is another item
  ~2 And this is the second item (except in the third slot?)
  

  Which ironically ends up hindering readability more than not having numbers at all.
• Keeping track of counts. This is closely related to the previous point. No longer is it your job to make sure you're properly numbering the ordered list items in ascending order, you have to keep track of which bullet point you're in at all times which is still a bit of mental overhead.

Besides we're not actually the first to have this idea! You'll find the #. syntax in a decent chunk of alternate markup formats like RST (I believe pandoc even has a markdown extension that implements said syntax?). It just makes more sense to have a machine count for you :)

Hope that clears things up a little!

[gzagatti]

Hi! Thanks for your very comprehensive response. I am happy to leave the spec as it is. You guys are doing an amazing job in putting this together so fast. However, let me just leave some additional thoughts if you eventually reconsider this position.

• I was not aware that detached modifiers could have extra segments. I could not find that discussion in the spec. An alternative would be to consider the following. (I think that leaving the extra space between the modifier and the segment actually looks better). However, I am not sure how segments are defined and whether they could be dynamic.

~ 1 This is an item
~ 2 The book

• I'm not advocating for either one syntax or another, but rather for both. Much like Asciidoc does. The writer is then able to choose what suits her/him best. However, it would not be good advice to allow for a mixed syntax like below, or to allow the #ordered tag in manually ordered lists.

~ 1 This is an item
~ The book

• If the writer were to number the items her-/himself, it would be indeed extra maintenance work. However, the beauty of any markdown syntax is that the extra maintenance pays off in terms of a plain text file that is easy to read and great on the eyes --- a true piece of design. If ordered lists can be hard to maintain, don't even consider markdown tables :)

  In addition, to that any text refactoring can be painful. I could start with an ordered list and realize that I really want headings. Or that the items are better expressed as paragraphs, etc.

• Norg is already auto-numbering ordered lists via concealing. The end result for the writer is that the lists are de-facto auto-numbered. Therefore, there could be an option to either use conceal or to modify the text in place. I don't think this is bad per se, it's letting the machine count for us. That's the reason for using text editors.

• I do agree that ordered syntax without numbering is pretty common, examples also include HTML and Latex. I write a lot of Latex and I do understand that it is indeed easier to maintain a list in plain text if numbers are not included. However, in my opinion plain Latex and HTML are markup languages that look damn ugly despite being pretty useful. It's actually hard to find a markup languages that are visually pleasing and easy to parse, since humans and machines process text and visual elements differently.