Overhaul HTML Formatter Delegation

[jneen]

Fixes #2279.

Reverts #1156 and #1083, and adds warning comments to all the HTML* formatters that take delegators.

In the above patches, there was a strict assumption that all HTML formatters were capable of being wrapped, which they are not, which caused all manner of confusion, extra newlines, extra wrapping tags, etc. In general, it is only safe to call the #span(tok, val) method of a delegator, which will yield precisely a span for that token. Calling #stream directly can be safe, but only for the non-nesting HTML formatters, which are HTML, HTMLInline, and HTMLDebug, which guarantee no newline-handling or wrapping of their input.

I have also added a temporary polyfill for #1082, with a deprecation warning. HTMLTable.new(...), when passed a Formatter other than one of the three non-nesting HTML formatters, will become an HTMLLegacyTable and warn. Those using that kind of nesting should maintain their own formatters for their application going into the future. Other unsupported combinations will raise. Users who have written their own formatters should not be affected by any of these changes.

If there is a desire for a more packaged approach, then others are welcome to publish a plugin with fancier HTML formatters. As it is, this stack is far too complicated for Rouge core.

Request for comment from @UlyssesZh, @mojavelinux, and @ashmaroli.

[jneen]

In particular, @mojavelinux, I think asciidoctor should be using a custom formatter. I am happy to contribute one.

[jneen]

Actually it looks like asciidoctor is using custom formatters, which is nice to see. It does seem to be passing an ignored parameter :inline_style into the plain Rouge::Formatters::HTML though.