Document how HTML parsing works

[RobertDober]

Spinoff from #356

The following shall go into the documentation:

Also check why oneline tags are broken? Did I miss a regression in #353?

---

Here is what kind of HTML Earmark supports, and I will update the documentation which is not good (was even missing lately)

• Oneline HTML Tags

   <tag...>{content}</tag>{suffix}

which will render

   {"tag", [], ["content"], %{verbatim: true}} # 1.4.6 format

• One level of a block

<tag>
    {content}
</tag>

{"tag", [], [content], %{verbatim: true}}

[sreyansjain]

Earmark.as_html!("<mark>Test</mark>")

produces

"<p>\n  &lt;mark&gt;Test&lt;/mark&gt;\n</p>\n"

Earmark.as_html!("<span>Test</span>")

produces

"<p>\n  &lt;span&gt;Test&lt;/span&gt;\n</p>\n"

It was fine in 1.4.4

[sreyansjain]

In 1.4.4 Tweet embedding as is worked. But now its getting incorrectly parsed in 1.4.5

You can try with this

<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Destiny does not happen without action.</p>&mdash; Mikael Cho (@mikaelcho) <a href="https://twitter.com/mikaelcho/status/1275454780819685377?ref_src=twsrc%5Etfw">June 23, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

[RobertDober]

@sreyansjain thank you for your comment

I do not think the current behavior or 1.4.4 is what we want, we want a oneline tag to be parsed as HTML

Concerning your Tweet example, that will definitely not work in 1.4.* but hopefully in 1.5 (c.f. #358)

[RobertDober]

Also document how comments are parsed #361

[lud]

Hello,

I found that

    """
    <meta>
    key value</meta>


    Hello
    """

Parses as

[
  {"meta", [], ["key value</meta>", "", "", "Hello"],
   %{meta: %{verbatim: true}}}
]

[RobertDober]

This will be fixed in 1.4.10