mbakeranalecta
commented
7 years ago An alternative is to call these something other than simple "comment". If they are a distinct object, then they can be treated differently by the schema. "Remark" seems like a reasonable name.
It is not that we could not call them "comments" in XML, since and element with that name has nothing to do with a comment element, but it could cause confusion to writers, and it would mean two objects in the SAM doc structure both named "comment". Also, comments have a well understood broad purpose in code and data formats. Using "remark" lets us define a more specific purpose. It also implies the requirement for attribution.
This would then give us this output:
<remark author="mbaker">This is a fine comment.</remark>
One of the most frequent uses of comments in documents is for commentary and discussion between writers, editors, and reviewers. In such cases, it is important to identify the author of the comment. All document commenting systems in apps like Word have this built in. Given SAM's specialized purpose for document production, it could make sense to support comments with attribution at the concrete language level.
In keeping with the pattern of using parens for annotations, this could be done like this:
This looks good and SAM like, but it raises two questions.
Do we support any other annotation on comments? It is not clear to me what purpose this would serve. They are not part of output so no need to apply conditions. Technically you might want to create a reference to them, but this seem esoteric. There is nothing to stop you creating your own block-based comment system if you want to, so no need to support esoteric cases.
How should comments be output to XML.
Current practice is to simply output XML comments. But are XML comments the right format? XML comments are essentially comments on the source, rather than comments on the document. Do we need comments on the source, really? And the problem this is what to do with the author annotation. Do we invent a format within the XML comment for recognizing the author name? But this then requires complex processing of the comment text for any kind of display.
We could output comments as elements:
This would allow you to easily show comments in a draft presentation.
The issue here, though, is that while XML comments are allowed anywhere by default, and XML schema would have to explicitly permit a
commentelement everywhere. (Presumably SAM schemas would permit them by default.We could allow users to choose whether they want XML comments of comment elements via a parser flag. This is compatible with other proposed flags to control XML output as in #88.