Spurious SAM parser warning: Unannotated phrase found:

0x8000-0000 commented 4 years ago

Considering this input:

$ cat test_phrase_condition.sam 
!annotation-lookup: case insensitive
!smart-quotes: on

example: Title

    section:(?some=time)
        {Hard}(?when=weekday){Easy}(?when=weekend) day ahead!
        {Pack the cooler!}(?when=weekend)

Produces this:

$ python3 ${HOME}/tools/sam/samparser.py html test_phrase_condition.sam

SAM parser information: Parsing /home/fiucha/tmp/test_phrase_condition.sam
SAM parser warning: Unannotated phrase found: {Hard} If you are trying to insert curly braces into the document, use \{Hard}.
SAM parser warning: Unannotated phrase found: {Easy} If you are trying to insert curly braces into the document, use \{Easy}.
SAM parser warning: Unannotated phrase found: {Pack the cooler!} If you are trying to insert curly braces into the document, use \{Pack the cooler!}.
Using css: None
Process completed with 0 errors.
<!DOCTYPE html>
<html>
<head>
<title>Title</title>
<meta charset = "UTF-8">
</head>
<body>
<div class="example">
<h1 class="title">Title</h1>

<div class="section" data-conditions="some=time">
<p class="p"><span class="phrase" data-conditions="when=weekday">Hard</span><span class="phrase" data-conditions="when=weekend">Easy</span> day ahead! <span class="phrase" data-conditions="when=weekend">Pack the cooler!</span></p>
</div>
</div>
</body>
</html>%

The warning seems spurious since the phrases are clearly annotated - the conditions are present in the output.

mbakeranalecta commented 4 years ago

What is happening here is that SAM makes a distinction between annotations and attributes. Annotations are for semantic markup that describes the what the content means. Annotations are for management doman markup that describes how it is to be processed. Attributes are denoted with symbol prefixes. Annotations are not. So the warnings are correct, there are no annotations on those phrases, just attributes.

This is certainly one of the less obvious parts of the SAM language design. It is a reflection of the fact that SAM was designed to support semantic markup with lightweight syntax, so the semantic approach is favored over the use of management domain attributes at every turn. (Same argument as in the case of attributes on records.)

Could this be better flagged to the user? Certainly.

Is it an appropriate thing to warn the user about at all? Yes. Because of annotation lookup, it is important to raise a warning for unannotated phrases.

Is the distinction between annotations and attributes important? Yes, if for no other reason than annotation lookup (which is a big timesaver) appropriately works for annotations and not for attributes.

Should phrases with attributes but no annotations raise this warning. Yes, because there is the possibility that the user was relying on annotation lookup and no matching annotations were found.

Could it be worded better (or a different wording be chosen in these cases)? Maybe.

0x8000-0000 commented 4 years ago

What would be a good way to indicate that this is what I mean, and I don't want this particular warning? (sort of like a cast in C/C++?)

mbakeranalecta commented 4 years ago

There isn't one, as far as I recall. I don't think the question has been raised before. I suppose a directive at the top of the file could be used to turn it off globally.

⁣Sent from TypeApp

On Feb 10, 2020, 2:46 PM, at 2:46 PM, Florin Iucha notifications@github.com wrote:

What would be a good way to indicate that this is what I mean, and I don't want this particular warning? (sort of like a cast in C/C++?)

-- You are receiving this because you commented. Reply to this email directly or view it on GitHub: https://github.com/mbakeranalecta/sam/issues/205#issuecomment-584316696

mbakeranalecta commented 4 years ago

!expect-unannotated-phrases: yes/[no]/with-attributes maybe?

mbakeranalecta / sam

Spurious SAM parser warning: Unannotated phrase found: #205