Markup of normative requirements (RFC 2119)

[mlagally]

Introduce markup of assertions, i.e. self contained sentences/paragraphs that contain keywords such as (MAY, MUST,... ).
These need to be compliant with the tooling (currently in a subdirectory of the TD repo)
to create the implementation report.

For tooling see: https://github.com/w3c/wot-thing-description/tree/main/testing

[mlagally]

add span tags and run the tooling to see whether the specification and the markup tooling work together.

Format:
<span class="rfc2119-assertion" id="td-security-activation"> The value assigned to <code>security</code> in an instance of <a>Class</a> <code>Thing</code> MUST be serialized as JSON string or as JSON array whose elements are JSON strings.</span>

See also the TD spec for additional examples.

[benfrancis]

I think this has been done now? Can I suggest not adding redundant semantically meaningless spans everywhere though? This is bad practice in HTML. Applying class="rfc2119-assertion" to existing semantic HTML elements like <p> and <table> should be sufficient. Propose closing unless there is more work to do?

[benfrancis]

Note that #227 identified some remaining issues with assertions and IDs, e.g. IDs which still include section numbers, and duplicates.

Once the document structure has settled a bit we should do a clean sweep of all of these IDs. Make them consistent, make sure they're in order, with no gaps, and remove duplicates.

I've tentatively added the "blocks publication" label so this isn't forgotten, but a "blocks testing" label would be more accurate if someone wants to create that, since the IDs are still a bit of a mess.

[mlagally]

@benfrancis There was a lot of work done wrt. RFCs.
Please let me know if you still see an issue.

[benfrancis]

This is a lot better than it was.

It would be nice to do another sweep and clean up the assertion IDs to be incrementing integers rather than all the in-between 1a, 1b, 1c etc. so that we start with a neat list, but that's not essential.

atrisk.css is totally out of sync now (sorry), but to be honest I don't think we really know exactly which assertions are at risk until we start testing so we may need to start again with that list.

[egekorkan]

My suggestion would be to never use numbers for ids of assertions. At some point, some people will need to read the assertion ids (like for filling the manual.csv) so the more verbose the ids are, the better.

[mlagally]

@egekorkan
Thanks for your suggestion.

manual.csv now also contains a textual description, see https://github.com/w3c/wot-profile, so your concern is addressed.