Change normative language in Microsyntax non-normative section

[evanp]

I changed MAY, SHOULD NOT and SHOULD to alternate phrasings that don't suggest normative language.

[evanp]

For #622

[trwnh]

Instead, publishers make appropriate use of the vocabulary terms provided specifically for these purposes.

the guidance isn't for publishers only, so i would take out the word "publishers":

Instead, make appropriate use of the vocabulary terms provided specifically for these purposes.

or even:

More appropriate vocabulary terms exist that are provided specifically for these purposes.

[evanp]

The guidance is for publishers only, according to the AS2 meaning of "publisher".

https://www.w3.org/TR/activitystreams-core/#publishers

A publisher is any implementation that creates AS2 documents. The other implementation type is a consumer, which reads and uses AS2 documents.

By definition, only publishers can add vocabulary terms to documents.

[csarven]

"not required" still cuts close to RFC2119 terminology since "required" is explicitly stated. I suggest using "cannot be expected" which reframes it as advisory guidance without implying a rule. Adding "are encouraged to" similarly signals advisory / best practice. Changes the tone rather than being descriptive.

Made inline suggestion.

This is part of a proposal to practice using reserved advisement level keywords consistently in the specification. See #671

[trwnh]

By definition, only publishers can add vocabulary terms to documents.

Consumers are the ones who parse (or don't parse) as:content for microsyntaxes, so it goes both ways.

[trwnh]

superseded by #676

[TallTed]

Rather than a new PR, which pretends that the discussion in this PR #627 didn't happen, the changes now in PR #676 should have been incorporated here, via a suggestion like this --

Suggested change

- The second paragraph in the non-normative section "Mentions, Tags and Other Common Social Microsyntaxes" contains RFC 2119 capitalized terms like MAY, SHOULD NOT, and SHOULD, which gives the impression that the requirements are normative. One solution is to replace the capitalized terms with equivalent terms that don't suggest normative requirements: 'While such microsyntaxes can be used within the values of the `content`, `name`, and `summary` properties on an Activity Streams Object, implementations cannot be expected to parse the values of those properties in order to determine the appropriate routing of notifications, categorization, or linking between objects. Instead, publishers are encouraged to make appropriate use of the vocabulary terms provided specifically for these purposes.'

- The second paragraph in the non-normative section "Mentions, Tags and Other Common Social Microsyntaxes" should read, 'While such microsyntaxes can be used within the values of the `content`, `name`, and `summary` properties on an Activity Streams Object, implementations are not expected to parse the values of those properties in order to determine the appropriate routing of notifications, categorization, or linking between objects. Instead, publishers are expected to make appropriate use of the vocabulary terms provided specifically for these purposes to communicate information to consumers.'

[trwnh]

evan made a new pr because this one had unresolvable merge conflicts.

[TallTed]

@evanp made a new pr because this one had unresolvable merge conflicts.

Well, that's frustrating, on multiple levels.

In future, best to comment about such "unresolvable merge conflicts" when closing the PR.

(I've never seen "unresolvable merge conflicts," only "merge conflicts that take significant time and effort to resolve." When I've been involved in such cases, I've made use of an external text editor, usually BBEdit, to manually compare the >>> and <<< sections on a character-by-character level and produce a clean-up commit. I'd be happy to do so for future PRs that are so "unresolvable". Note that I'd need to be granted some extra permissions on the repo, which I'd only use for production of such conflict resolution commits.)

[evanp]

@TallTed let's say that the PR was not resolvable with my level of attention and skill, and that it was significantly easier to do without a merge. If in the future it seems like it would be better to have someone untangle the merges, I'll definitely tag you in!