Remarks cannot precede the root block

Remarks are a variation on comments, but while comments can precede the root block, because they serialize to XML comments, remarks cannot, because they serialize to XML elements.

First, we need to make sure that this restriction is enforced by the parser so we don't create invalid XML.

Then we need to think about usability implications.

The current distinction between comments and remarks syntactically is small enough that different nesting rules are likely to cause confusion. Alternatives to consider:

Different syntax of remarks.
Not permitting comments before the root block.
Serializing comments and remarks declared outside the root block inside the root block.

Of these, I am initially leaning towards the third option. The fact of the matter is that insofar as commenting on the document as a whole is concerned, there is little or no semantic difference between entering the comment before the root block or after it. In other words, it would seem unlikely that the move would violate the writer's intention.

If we do this, though, we have to decide if the translation happens on parsing, which would mean moving them before the SAM DOM is created, or moving them on serialization. There is nothing inherently wrong with allowing these structures before the root block in the SAM DOM. This issue is really all with the rules of XML. SAM does not have to be tied to XML structurally, as long as serialization is straightforward and predictable.

mbakeranalecta / sam

Remarks cannot precede the root block #113