callout list handling could be better

[gdamore]

While working on #721 I noticed that the handling for callout lists is a bit dodgy, and differs in some ways from asciidoctor -- in particular the use of CSS to separate callouts is good, but when these appear in a source block comment, the comment itself is not detected.

What asciidoctor does is look for certain comment patterns, and when finding those as the sole comment, replaces the entire comment with the callout reference.

asciidoctor does this using a naive regular expression.

We think a clever approach might be to replace the callout reference with a special unicode token, that we can then come back and replace with appropriate text. We can also benefit from the lexer that is part of Chroma, and let it do the work to identify this for us. Essentially we'd replace the comment with the inlined callout item.

We also think we can do something nicer than asciidoctor here. Asciidoctor uses either font icons or images -- but this is kind silly -- unicode has nice circled variants for most numbers, and we can simply translate them, leaving elegant markup behind us, and eliminating the dependency upon font icons, svg, or anything like that.

[gdamore]

Actually, it might be easier to just let this get treated in a similar way -- handle it naively at parser time. We will probably want to recognize each of the ways that asciidoctor does.

[xcoulon]

One thing to keep in mind is that Asciidoctor renders the callouts in such a way that a reader can copy/paste an entire block of code without the callout references even if they appear on the HTML document (see https://asciidoctor.org/docs/user-manual/#copy-and-paste-friendly-callouts). Or maybe that's what you meant by "n particular the use of CSS to separate callouts is good"?

[gdamore]

Yep, it's handled via CSS and the user-select property -- at least in theory.

They also use CSS to render the surrounding circle, but note that their code has limitations around the number of callouts (or at least digits in the callout number) and does not work well when using non-consecutively numbered callouts. (None of this is documented btw.)

I actually think we could use the dingbat items in unicode, like this: ➊ to get the same effect (for at least up to 10 callouts), and we could still use the CSS styles to keep them from being selectable.