Numeric list syntax

[domenic]

/cc @bterlson @jorendorff

The current list design (0. prefix; 2 space indents) is the result of tc39/ecmarkup#3.

In #4 @tabatkins points out that CommonMark has lists start at the number that appears in the source, instead of always starting at 1. I don't think we want to allow freedom in list construction, but there is an argument for using 1. instead of 0..

A second, and related question. Currently we go with 2-space indents per the linked issue. IMO this looks a little weird since the 0. for a nested list actually lines up with the space from the above list. Compare 2-space, 3-space, and 4-space indents:

0. Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
0. ReturnIfAbrupt(_hasReturn_).
  0. If _hasReturn_ is *true*, then
    0. Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
    0. If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
      0. Return _innerResult_.
0. Return _completion_.

0. Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
0. ReturnIfAbrupt(_hasReturn_).
   0. If _hasReturn_ is *true*, then
      0. Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
      0. If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
         0. Return _innerResult_.
0. Return _completion_.

0. Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
0. ReturnIfAbrupt(_hasReturn_).
    0. If _hasReturn_ is *true*, then
        0. Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
        0. If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
            0. Return _innerResult_.
0. Return _completion_.

The most natural is 3 space indents... or we could come up with another delimiter that makes 2-space indents work. Maybe just .? Or drop the prefix altogether and let it be entirely done with indentation? This latter looks like

Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
ReturnIfAbrupt(_hasReturn_).
  If _hasReturn_ is *true*, then
    Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
    If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
      Return _innerResult_.
Return _completion_.

[jorendorff]

All of these look fine to me. In the absence of any strong reason to pick one over the others, I propose we just do whatever Common Markdown does. (1. prefix, 4-space indent?)

[tabatkins]

CMD does "the same indent as the first line". However many characters there are between the start of the line and the start of the text on the first line, that's how many you need on subsequent lines to avoid breaking out of the list, which ensures that lists are always visually lined up (or at least indented as much or more than the first line):

1. This item starts as soon as possible,
   so subsequent lines need 3 spaces of indent
    though 4 or more is fine too.
2.   This item has more spaces before it starts,
     so subsequent lines need at least 5 spaces to line up.

This usually translates into 3 or 4 spaces, depending on whether the item has one or two digits in its list marker. I still don't understand why you'd want to have numbers be all the same, but given that, it means a 3-space indent or more is required.

[domenic]

@bterlson has convinced me that, in the spirit of write-once read-often, we should prefer explicitly numbered lists.

In general I am warming to the strategy of just doing (something close to) CommonMark semantics, and having an "Ecmarkdown lint" that enforces our preferred style.

[tabatkins]

Excellent!

I don't see much reason to depart from CommonMark block semantics, at least, and just redefining a bunch of inline things to be better suited for algorithms.

[jmdyck]

@bterlson has convinced me that, in the spirit of write-once read-often, we should prefer explicitly numbered lists.

By "explicitly numbered lists", do you mean lists in which each item in the source is prefixed by the numeric label that it should have in the result? If so, consider what happens when you insert or remove an item: all subsequent items in the list have to be renumbered. Even if you automate the renumbering via a commit hook, it'll still create spurious diffs between revisions.

(Of course, this problem doesn't occur if the source is truly "write once", but history indicates that the ES spec isn't.)