Expose Ability to Get the Number Of a List Item

[bfoersterling]

rationale

The function cmark_node_get_item_number() improves the user friendliness
of the API as the library user does not have to implement a logic to derive
the number of a list item.

It is more efficient to store the item number once when parsing the markdown
content.
The function cmark_node_get_item_number only has to look at the previous
node. The library user might need to traverse until the start of the list
if he does not want to store the item numbers in a separate data type.

implementation

I added the new type cmark_item and made it a union member for the as
member in cmark_node.

The item number is calculated and stored in the function finalize().

[jgm]

@nwellnhof any objections to this?

[nwellnhof]

It seems trivial to count list items manually, so I don't think we need an additional API function. It might also be confusing that the returned values aren't guaranteed to match the values from the source file which don't have to be consecutive or increasing. For a input like

5. five
2. two
4. four

people might expect the function to return values 5, 2, 4 instead of 5, 6, 7.

Besides, what should happen if the tree is updated?

[bfoersterling]

Thank you for the review.

It might also be confusing that the returned values aren't guaranteed to match the values from the source file which don't have to be consecutive or increasing. For a input like
5. five
2. two
4. four
people might expect the function to return values 5, 2, 4 instead of 5, 6, 7.

But is that expectation correct for an ordered list and is it satisfied with the current implementation of cmark?

In html ordered lists (<ol>) are consecutive and have a stride of 1.
They can be reversed, but according to the Commonmark spec this attribute
is never set, so it seems like reversed lists are not supported.

This example would produce this html when converted by cmark:

<ol start="5">
<li>five</li>
<li>two</li>
<li>four</li>
</ol>

And this renders in firefox to this:

5. five
6. two
7. four

This would also mean, that the current implementation of cmark -t man is incorrect.

.IP "5." 4
five
.IP "6." 4
two
.IP "7." 4
four

The tags for the .IP macro are also consecutive and not 5, 2, 4.

Besides, what should happen if the tree is updated?

I assume you mean the functions cmark_node_set_list_type, cmark_node_set_list_delim,
and cmark_node_set_list_start.
Why not add a function update_item_numbers that is called at the end of those three functions?
That function traverses the list (not the entire tree) and updates the item numbers.

[jgm]

You are right about cmark behavior. I think the worry was that people might expect to get the number in the markdown source. So this could be a confusing feature.

The question is whether it is worth adding complexity (which is always a negative) in order to facilitate something that can be done quite easily in a renderer or other processor by counting. I'm not convinced that it is.

[nwellnhof]

Besides, what should happen if the tree is updated?

I assume you mean the functions cmark_node_set_list_type, cmark_node_set_list_delim,
and cmark_node_set_list_start.

No, I meant what should happen if list items are added to or removed from the tree. Updating the list numbers can't be done in constant time.