markdown

Overview ¶

Command markdown converts the subset of HTML it understands to Markdown, and says what it dropped.

The subset is deliberate: headings, paragraphs, lists, links, emphasis, code, blockquotes, horizontal rules and line breaks. Everything else keeps its text and loses its markup, and the tags that were dropped are reported, because a converter that silently discards <table> is worse than one that says it cannot do tables.

The reason this is a different program from examples/gip/plaintext, rather than the same one with delimiters, is that Markdown needs to know where an element *ends*, and this library will not reliably tell you.

An end-tag handler runs when the element's content ends, and it is handed the tag that closed it, which is not always the element's own. Measured, with "when" meaning where in the stream of reported content the callback lands:

<p><em>a</em> b</p>       closes at </em>, own tag, exactly at the end
<p><em>a</p>b             closes at </p>, an ancestor's, exactly at the end
<ul><li><em>a<li>b</ul>   closes at </ul>, an ancestor's, but "b" was
                          reported first: the <em> ended at the second <li>
<p><em>a                  never closes at all

The third row is why the callback is not enough on its own: the emphasis ended two tokens ago and nothing says so. So this program keeps the stack of open elements itself and applies the specification's implied end tags, the same way examples/gip/depth does, and closes emphasis when the stack pops rather than when a callback arrives. The fourth row is why it also closes everything left open at the document end.

The other half of the work is escaping, in the opposite direction from the library's. Text that means nothing in HTML means something in Markdown - "*emphasis*", "# heading", "1. item", a backslash - so it is escaped on the way out, and not escaped inside code, where Markdown does not read it.