Precision regarding 'html_block' and EscapeHtml

[benjaoming]

I noticed that the extra extension set doesn't work with the EscapeHtml example in the release notes and made a remark about this.

I'm not sure if the extra should be fixed because of this or if it's an inherent decision from the way things are supposed to work with this set of extensions.

Also added some missing indentation.

[waylan]

Hmm, so the "extra" extension adds support for markdown=1 to parse Markdown text inside raw HTML blocks. But the EspaceHTML extension effectively disables raw HTML parsing. Of course the two are mutely exclusive. Not sure why that needs to be pointed out.

[benjaoming]

I'm not that interested in the internals of the extra extension set, but it's very commonly enabled. Not sure of the stats, but wouldn't it sound reasonable to say that 50% of users can't use the EscapeHTML approach?

Also, MarkdownInHtmlProcessor is enabled through the extra extension which is a bit blurry to me.. is it like a dependency of all the other extra extensions?

[benjaoming]

(renamed extras=extra)

[benjaoming]

Btw I can see Coveralls is freezing up as I've seen so many other times.. I ended up replacing it with CodeCov.io in most of my repositories after having had so many problems with Coveralls... basically gave up on it.

[waylan]

The "extra" extension is just a shortcut which enables all of the various extensions necessary to implement the features which most closely match PHP Markdown Extra. It exists mainly for historical reasons which are no longer relevant.

The one exception is that "extra" also adds the MarkdownInHtmlProcessor which does not exist in a separate extension of its own. Basically it implements an incomplete (and undocumented) clone of PHP's Markdown Inside HTML Blocks feature. It is not connected to any other extensions in any specific way. The intention was to break it out into its own extension when it was improved to a point where it made sense to advertise and document it (when it came out of beta). But that never happened and today I believe it is not the best solution for supporting Markdown inside raw HTML. As we never documented it, few users have made use of it and I doubt it will survive the move to version 3.0. For that matter, I doubt the "extra" extension will survive to version 3.0.

So, yes, "MarkdownInHtml" and "EscapeHtml" are mutually exclusive. You can't have both. But given that the former is completely undocumented (and not officially supported), I'm okay with that and don't want to start documenting it now. Therefore, I don't want to document the conflict either. For that reason, I am closing this PR. If you want to create a new one for the indentation fix, you are welcome to. Otherwise I'll do that myself later.

If you want "extra" and "EscapeHTML" just enable the various extensions under "extra" individually along with the "EscapeHTML" extension and things should work fine. In fact, the Markdown inside raw HTML will still get parsed as the parser has no knowledge of HTML tags in that case.

[benjaoming]

You'll go an awfully long way to reject a simple precision for the documentation, I'll give you that. Thanks for the explanation. Of course it makes sense, and I never contested your explanation... I just wanted to share it with other users and documentation readers.