Keep track of ordered list indexes and render them

[simmsb]

Currently, when ordered lists are parsed the sequence/index numbers of the list
items are discarded at the parser.

This PR changes DocOrderedList to also keep track of the sequence number, and
updates the HTML and JSON (though I'm unsure on how changes to the JSON backend
should be dealt with) backends to include these. The hoogle backend remains
unchanged.

Resolves #1406

[Kleidukos]

Thank you very much @simmsb. :) Could you please indicate each time the index appears in a tuple/function parameter that the variable is indeed an index? Such as replacing (x, a) with (index, a)? :)

[mpickering]

Commonmark only pays attention to the first index in the list. So for example:

1. foo
3. foo

Renders as

1. foo
2. foo

https://spec.commonmark.org/dingus/?text=1.%20asdsad%0A3.%20asdasd%0A

[simmsb]

Seems so, would that be the preferred behavior?

[Lysxia]

I wonder what the reason for that spec is. I once read that it reduces diffs when you remove an element in the middle of a large list, but that seems a rather niche concern. For a tool like haddock it seems preferable to give more control to the user.

[sol]

1. This is a breaking change and this breaks existing documentation!

   Specifically, it is a common pattern to introduce each list item with 1., say:

   1. foo
   1. bar
   1. baz
   

2. There is prior art for the original behavior. Other formats, like Markdown (CommonMark, GFM, ...), MediaWiki and RST don't require you to micromanage list indices. For a user who is familiar with those formats, the new behavior is surprising.

3. In software development, if I have two alternative options on how to proceed, if I can make an equally good case for both options, but one of the options is backwards compatible and the other option introduces a breaking change, then I proceeded with the backwards compatible option.

From my perspective it would have been better if this PR would never have landed, but that ship has sailed. I think the best bet for damage control is to do what CommonMark and GFM do and

only pays attention to the first index in the list

as @mpickering pointed out.

As for the motivating example from #1406, I think this is what definition lists are meant for.