search

speced / respec

A tool for creating technical documents and web standards
https://respec.org/
Other
725 stars 390 forks source link

RFC 2119 keyword boilerplate incomplete #345

Closed palemieux closed 10 years ago

palemieux commented 10 years ago

In the conformance section, the keyword boilerplate does not match RFC 2119. Specifically, the keywords "SHALL" and "SHALL NOT" are missing.

" The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119."

marcoscaceres commented 10 years ago

SHALL and SHALL NOT generally don't appear in W3C specs.

marcoscaceres commented 10 years ago

To be clear, it's preferable that specs only use one way of saying things - specially with the most critical of conformance requirements (i.e., MUSTs).

palemieux commented 10 years ago

"SHALL" and "SHALL NOT" appear in a number of W3C specifications, e.g. [1]

[1] http://www.w3.org/TR/xmldsig-core1/

Also, RFC 2119 specifically states:

Authors who follow these guidelines
   should incorporate this phrase near the beginning of their document:

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
      "OPTIONAL" in this document are to be interpreted as described in
      RFC 2119.

Since RFC 2119 is specifically cited, the cited text should be verbatim.

Finally, ISO (as well as other SDOs) recommend against using 'must' to 'avoid any confusion between the requirements of a document and external statutory obligations.' [1]

[1] http://isotc.iso.org/livelink/livelink?func=ll&objId=4230456&objAction=browse&sort=subtype

Certainly, specifications SHALL NOT use both MUST and SHALL :)

marcoscaceres commented 10 years ago

I'll defer to the other two maintainers, but this gets a "no" vote from me.

palemieux commented 10 years ago

Can you be more specific in your 'no' vote, e.g. cite W3C process text or examples where the proposed course of action is not desirable?

marcoscaceres commented 10 years ago

I can try. As I stated originally, irrespective of ISO and W3C process, I feel that having "SHALL" encourages use of that word were "MUST" would be used. I think that is dangerous because a lot of people cite RFC2119 but have never read 2119. In addition, the use of the word shall is not as commonly used as must.

The standards that I refer to are the "core" ones to the Web Platform (HTML, DOM, etc.). It might be possible, as you've shown, to find examples in more obscure specs (e.g., xmldigsig). For the core platform, it's important, IMO, to keep terminology as consistent as possible. I feel adding SHALL would add a vector for confusion.

That's just my 2c.

halindrome commented 10 years ago

There would likely be a problem with the pubrules checker too. It looks for fairly specific strings. I tried to fix a problem with the copyright statement (it doesn't use an Oxford comma, which makes me insane) and was rebuffed because it would have required a complex modification to pubrules.

On Fri, Oct 3, 2014 at 1:10 PM, Marcos Caceres notifications@github.com wrote:

I can try. As I stated originally, irrespective of ISO and W3C process, I feel that having "SHALL" encourages use of that word were "MUST" would be used. I think that is dangerous because a lot of people cite RFC2119 but have never read 2119. In addition, the use of the word shall is not as commonly used as must https://www.google.ca/trends/explore#q=shall%2C%20must&cmpt=q.

The standards that I refer to are the "core" ones to the Web Platform (HTML, DOM, etc.). It might be possible, as you've shown, to find examples in more obscure specs (e.g., xmldigsig). For the core platform, it's important, IMO, to keep terminology as consistent as possible. I feel adding SHALL would add a vector for confusion.

That's just my 2c.

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-57832669.

Shane McCarron halindrome@gmail.com

palemieux commented 10 years ago

I ran [1] through pubrules and no errors/warnings were issued against "SHALL"/"SHALL NOT".

[1] http://www.w3.org/TR/xmldsig-core1/

So it looks like we are clear there.

halindrome commented 10 years ago

Huh - thanks for checking.

On Fri, Oct 3, 2014 at 5:51 PM, palemieux notifications@github.com wrote:

I ran [1] through pubrules and no errors/warnings were issued against "SHALL"/"SHALL NOT".

[1] http://www.w3.org/TR/xmldsig-core1/

So it looks like we are clear there.

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-57874045.

Shane McCarron halindrome@gmail.com

palemieux commented 10 years ago

P.S.: One approach could be to have a default "keywords" statement that could be overridden as a configuration option.....

halindrome commented 10 years ago

ReSpec is a tool, and the (primary) target audience is the W3C. I think the smart thing to do here is loop in IanJ and whomever else are in the publication process loop and get their perspective.

P.S. As an old school ANSI / IEEE / ISO standards author, I prefer to use SHALL and SHALL NOT, so it's not like I disagree with the general sentiment. But this isn't about what we as editors want. There are other important players in this mix.

On Fri, Oct 3, 2014 at 10:44 PM, palemieux notifications@github.com wrote:

P.S.: One approach could be to have a default "keywords" statement that could be overridden as a configuration option.....

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-57893678.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

I'm fine with it being an optional pref. as this is not a process question, involving IanJ is probably not worth the trouble. In context, this is adding 2 words to a section of a doc that no one reads.

halindrome commented 10 years ago

Okay. conf.include2119SHALL ?

On Sat, Oct 4, 2014 at 7:34 AM, Marcos Caceres notifications@github.com wrote:

I'm fine with it being an optional pref. as this is not a process question, involving IanJ is probably not worth the trouble. In context, this is adding 2 words to a section of a doc that no one reads.

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-57903844.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

maybe, allRFC2119.

What we should actually do is not take a political stance on this. We should build that particular part of the spec based on the RFC2119 keywords actually used in the document. Respec already autofinds those words when they appear in capital.

So, if you only ever use MUST, then it should just say: 

The key word(s) "MUST" in this document are/is to be interpreted as described in RFC 2119.

And so on... the above could be made to deal with singular uses and multiple uses of words. Then groups are free to use SHALL or any other word if that is convention in their community.

darobin commented 10 years ago

SHALL and SHALL NOT were deliberately removed, I wouldn't recommend adding them back.

The reason for their removal is that they bring nothing to the table while at the same time being more confusing, notably to non-native speakers. A number of tools that currently process W3C specifications (e.g. to find testable assertions, evaluate coverage) rely on MUST/SHOULD and don't know about SHALL. SHALL sounds like something given to you on a stone tablet.

Note that we're under no obligation to use all of RFC2119.

palemieux commented 10 years ago

I understand that some W3C specifications have chosen to not use "SHALL". Other W3C specifications use "SHALL". Unless/until W3C process forbids the use of "SHALL", I do not believe it is reasonable for a W3C tool to forbid it.

What is the downside to making "SHALL" an opt-in option?

gkellogg commented 10 years ago

I like @marcoscaceres suggestion of building the section based on actual RFC2119 terms used in the document. While some editors/groups may prefer not to use SHALL, they are allowed in RFC2119 so it is not unreasonable that they be used, unless W3M takes a different position.

halindrome commented 10 years ago

Yeah I like the idea of auto-generating the list of terms that are actually in the document.

On Mon, Oct 6, 2014 at 11:43 AM, Gregg Kellogg notifications@github.com wrote:

I like @marcoscaceres https://github.com/marcoscaceres suggestion of building the section based on actual RFC2119 terms used in the document. While some editors/groups may prefer not to use SHALL, they are allowed in RFC2119 so it is not unreasonable that they be used, unless W3M takes a different position.

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58047216.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

Ok, let's resolve to implement generating from what is in the actual document. What we can do later is add a "Web Platform Linter" that can warn about "SHALL" for that particular community as per @darobin's comments. That should address everyone's concerns.

halindrome commented 10 years ago

Okay. I created a branch for it. I will get it implemented tonight probably.

On Mon, Oct 6, 2014 at 4:48 PM, Marcos Caceres notifications@github.com wrote:

Ok, let's resolve to implement generating from what is in the actual document. What we can do later is add a "Web Platform Linter" that can warn about "SHALL" for that particular community as per @darobin https://github.com/darobin's comments. That should address everyone's concerns.

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58105459.

Shane McCarron halindrome@gmail.com

halindrome commented 10 years ago

Took me a little longer - day job got in the way. There is a patch up in w3c/respec branch patch-345. Take a look and see what you think.

On Mon, Oct 6, 2014 at 5:02 PM, Shane McCarron halindrome@gmail.com wrote:

Okay. I created a branch for it. I will get it implemented tonight probably.

On Mon, Oct 6, 2014 at 4:48 PM, Marcos Caceres notifications@github.com wrote:

Ok, let's resolve to implement generating from what is in the actual document. What we can do later is add a "Web Platform Linter" that can warn about "SHALL" for that particular community as per @darobin https://github.com/darobin's comments. That should address everyone's concerns.

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58105459.

Shane McCarron halindrome@gmail.com

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

Nice! Can you send it as a PR? I tried to review it, but it won't let me comment on your code :(

halindrome commented 10 years ago

This change is now in production - looks good!

On Tue, Oct 7, 2014 at 6:40 PM, Marcos Caceres notifications@github.com wrote:

Nice! Can you send it as a PR? I tried to review it, but it won't let me comment on your code :(

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58280852.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

Great work @halindrome! You rock-n-roller! :D

palemieux commented 10 years ago

Nice! Small nit perhaps: "SHALL NOT" appears twice at [1]

[1] https://dvcs.w3.org/hg/ttml/raw-file/72d5d67f1bcd/ttml-ww-profiles/ttml-ww-profiles.source.html

Operator error?

halindrome commented 10 years ago

Yikes! also yikes, that document is not loading / processing respec when I load it. I will look right away.

On Thu, Oct 9, 2014 at 10:45 AM, palemieux notifications@github.com wrote:

Nice! Small nit perhaps: "SHALL NOT" appears twice at [1]

[1] https://dvcs.w3.org/hg/ttml/raw-file/72d5d67f1bcd/ttml-ww-profiles/ttml-ww-profiles.source.html

Operator error?

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58529648.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

The document not loading is expected because:

"Blocked loading mixed active content "http://www.w3.org/Tools/respec/respec-w3c-common""

halindrome commented 10 years ago

Yeah, I see that. I expect I need to normalize the content to ensure there is no extra whitespace. I thought that was done already, but it is probably only for definitions.

On Thu, Oct 9, 2014 at 11:32 AM, Marcos Caceres notifications@github.com wrote:

The document not loading is expected because:

"Blocked loading mixed active content " http://www.w3.org/Tools/respec/respec-w3c-common""

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58537032.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

@palemieux can you please update your document to:

<script src='//www.w3.org/Tools/respec/respec-w3c-common'>

(i.e., drop the protocol)

halindrome commented 10 years ago

Reopening to ensure that whitespace is normalized so that there are no duplicate entries in the list of keywords.

palemieux commented 10 years ago

@marcoscaceres The script does not load locally if the <script> element is changed as proposed. Thoughts? Note that a rendered version of the document is generated at every commit, so the typical reader should not run into origin issues.

[1] https://dvcs.w3.org/hg/ttml/raw-file/72d5d67f1bcd/ttml-ww-profiles/ttml-ww-profiles.html

halindrome commented 10 years ago

Yeah that's a good point. What if you put https at the front?

On Thu, Oct 9, 2014 at 11:58 AM, palemieux notifications@github.com wrote:

@marcoscaceres https://github.com/marcoscaceres The script does not load locally if the

— Reply to this email directly or view it on GitHub https://github.com/w3c/respec/issues/345#issuecomment-58541250.

Shane McCarron halindrome@gmail.com

marcoscaceres commented 10 years ago

yeah, then just put https on the front. I run a local web server while doing stuff locally. It's good practice to do that, as with all the mixed-content rules on the web nowadays, it can be easy to overlook stuff.