tailcomment

Overview ¶

Command tailcomment emits a summary of what a rewrite changed as a trailing HTML comment, which is the shape a build stamp or a debug trace usually takes: invisible in the page, there in the source.

A comment is the one place a summary cannot be escaped into. Comment.SetText refuses text that would end the comment early, and there is no escaping that would work - nothing inside a comment is a character reference, so "-->" has no spelling a comment can hold. But SetText is not the path this program uses. A trailing comment is appended, and DocumentEnd.Append takes markup, so the comment is built by hand and nothing guards it. That is what lolhtml.CheckComment is for.

What happens without the check is not an error, which is the point:

summary          appended as <!--summary-->      what the document gets
3 changed        <!--3 changed-->                one comment
a-->b            <!--a-->b-->                    a comment "a", then "b-->" as text
>                <!-->-->                        an empty comment, then "-->" as text

So a summary holding text from the document - a tag name, an attribute value, a URL - can put markup into the page it was describing. Nothing errors and the output parses.

Since there is no escape, a caller has to choose, and this program makes the choice explicit rather than picking silently: Safe rewrites the offending sequences into ones that read the same to a person ("-->" becomes "- ->"), and Strict refuses to emit a comment at all and says why. Both are honest; a program that quietly dropped the summary would not be.