epub formatter allows non-conformant HTML comments

[adamwight]

When repackaging Markdown HTML as XHTML to build an EPUB, some changes have to be made to html comments like this:

<!--------------------- Don't add new entries after this line --------------------->

This is valid HTML, but XHTML disallows -- inside of a comment.[1]

epubcheck will emit a fatal-level error when parsing such content:

ERROR(RSC-005): ymlr.epub/OEBPS/content/changelog.xhtml(-1,-1): Error while parsing file: The string "--" is not permitted within comments.

It's not entirely clear if ex_doc should be responsible for this, but it would possibly be surprising to markdown documentation authors to find that XHTML constraints will be applied to their content, so maybe we enhance ExDoc.DocAST.to_string({:comment, _attrs, inner, _meta} to replace this illegal sequence with \-\-, -- or whatever.

If nothing is done to work around this in code, it would be polite to warn documentation authors about this and other XHTML constraints in ex_doc docs.

[josevalim]

Great find. Perhaps we should remove comments when emitting the markdown or, at least, when emitting XHTML?