John Gruber’s syntax guide defines the ordered list syntax as follows:
Ordered lists use numbers followed by periods:
Bird
McHale
Parish
Unlike the unordered list syntax, there is only one variation.
However, it is common for writers to use brackets to define list items instead of periods. My suggestion is to add two variations to the ordered list syntax:
Bird
McHale
Parish
and
(1) Bird
(2) McHale
(3) Parish
This syntax has likely been implemented in other Markdown flavours already, but I think we should discuss if and how it should be added to CommonMark - as an extension or as part of the core syntax?
I take the view that it is better to make the parser more complicated if it makes life easier for the writer. This is consistent with Markdown’s approach elsewhere. E.g. with unordered lists, some writers may find it more intuitive to use *, for others - is more natural.
Computers are fast and are only going to get faster. Parsing a Markdown file does not seem like a process that would be particularly resource intensive.
Are their real world examples of slow Markdown parsers causing performance issues?
In this case, the writer already knows the three different variations because they are used outside of Markdown. All three variations are used in books, articles, manuals, etc. By supporting all three variations, if the writer intends to write an ordered list there is a good chance that she or he is going to use one of the three formats. That’s without looking at a Markdown syntax guide. If we require the writer to check which variation is supported, we’ve made their life harder.
I think that’s okay. No one is being forced to use (1) instead of 1) or 1. All three would be supported, so you could choose a variation that requires less typing. It’s like how you don’t have to use unlined headings, but they are an option if that visual preference is a priority over quickness of typing. It’s quite a subjective decision.
It would be good to see some stats on this. Maybe adding this particular feature wouldn’t degrade performance significantly.
Are these examples commonly used though? I don’t recognise them from any texts I’ve read. 1., 1), and (1) seem to be the most common (along with Roman numerals).
This looks a lot more like a footnote or something alike, rather than an ordered list. I’ve never seen this syntax, either in markdown, or elsewhere, except for lists with not linebreak between items.
Huh? Is this in the CommonMark spec anywhere? I’m pretty sure I did not see this when I read the spec yesterday?
As for the problem at hand - I’d welcome the use of (1) as a ordered list bullet, it actually looks nice to me. Especially the example @mofosyne gives, referring back to an earlier number in running text is IMHO nicer as (1) than using 1. above or 1) above.
The counterargument to this, though, is that this looks good in markdown source, but in the rendered HTML, the list will always (at least usually) end up having 1. markers, which then no longer correspond with the (1) backreference…
Any of the three numeric ordered lists could output this HTML. The web designer could then customise the appearance of the ordered list, for example by adding a zero to the front of each list item with CSS:
ol {
list-style-type: decimal-leading-zero;
}
Because Markdown and HTML are agnostic about how elements are presented, this is fine. They could even change it to Roman numerals (list-style-style: lower-roman) or a number of other list styles. The designer could even change the numbers to bullets (normally used in unordered lists).
The reason for having (1) is not because it needs to map 1:1 with the output, but rather for predictability while writing it.