Check references category and stability #295

Closed
tidoust opened this Issue May 13, 2016 · 3 comments

Comments

Projects
None yet
3 participants
Contributor

tidoust commented May 13, 2016 edited

I'm creating this issue to track down references. It does not need to be addressed before publication as a Candidate Recommendation.

For the Presentation API to be published as a final W3C Recommendation, normative references will need to reference stable specs, the rule of thumb being that a Recommendation should normatively link to other Recommendations (or similar documents published by other organizations) and not to working drafts.

There may be exceptions to the rule, which should be documented in the Status of This Document section. For instance, since WebIDL is not yet a Recommendation, recently published specs have sentences such as "By publishing this Recommendation, W3C expects the functionality specified in this Recommendation will not be affected by changes to Web IDL as the WebIDL specification proceeds to Recommendation." as in the Web Storage spec:
http://www.w3.org/TR/2016/REC-webstorage-20160419/#status-of-this-document

Also, we need to ensure that references are correctly flagged as normative or informative, depending on how they get used in the spec.

Making a quick pass through the spec:

  • Check terms:
    • "in parallel", defined in HTML5.1.
    • WebIDL terms, although WebIDL Level 1 might move forward on the Rec track in the meantime
    • NotAllowedError, defined in WebIDL (Second Level) but not in WebIDL Level 1
    • Blob, defined in the File API spec
    • Terms defined in the Mixed Content spec
    • Terms defined in the Permissions spec
  • Convert to normative references (because of their use in the "create a receiving browsing context" algorithm):
    • Cookies
    • IndexedDB
    • Permissions
    • WebStorage
  • Consider updating the "create a receiving browsing context" to use prose such as "If the user agent supports IndexedDB, set the databases for C to an empty set of databases" to clarify that the action is conditional to the user agent supporting the feature in the first place.
  • Consider converting references to HTML 5.1 (Issue #396)

@tidoust tidoust added a commit to tidoust/presentation-api that referenced this issue May 13, 2016

@tidoust tidoust Fix link to WebIDL "throw" and update ref to WebIDL to target Second …
…Level

The <dfn> tags were incorrectly surrounding "term" instead of "throw".

Also, as alluded to in #295, "NotAllowedError" is only defined in
"WebIDL (Second Level)", and the spec referenced "WebIDL Level 1". I'm not
clear at this stage whether "NotAllowedError" will make it to Level 1, but it
seems better to reference Level 2 in the meantime.
7cfd529

@mfoltzgoogle mfoltzgoogle added a commit that referenced this issue May 26, 2016

@tidoust @mfoltzgoogle tidoust + mfoltzgoogle Fix link to WebIDL "throw" and update ref to WebIDL to target Second …
…Level

The <dfn> tags were incorrectly surrounding "term" instead of "throw".

Also, as alluded to in #295, "NotAllowedError" is only defined in
"WebIDL (Second Level)", and the spec referenced "WebIDL Level 1". I'm not
clear at this stage whether "NotAllowedError" will make it to Level 1, but it
seems better to reference Level 2 in the meantime.
b67ca69

anssiko added the v1 label Sep 7, 2016

@tidoust tidoust pushed a commit to tidoust/presentation-api that referenced this issue Jan 10, 2017

François Daoust Issue #396: Migrate HTML 5.0 references to HTML 5.1
This commit updates all HTML 5.0 references to HTML 5.1.

To help assess references stability (issue #295), the spec now also directly
references the WebIDL Level 1 Recommendation, pointing out that NotAllowedError
is defined in WebIDL Level 2. References to the WHATWG version of HTML for
"current settings object" and "relevant settings object" now target HMTL 5.1
as well.

Other changes introduced in this commit:
- Correct nesting of <a>, <code>, <dfn> to make sure code definitions get
styled in red as expected
- ReSpec now automatically supports aliases such as "start()" for method, so
dropped the now redundant alias definitions.
- Turned references incorrectly marked as informative into normative references
(UUID, cookies, RFCs).
65928d2

@mfoltzgoogle mfoltzgoogle added a commit that referenced this issue Jan 11, 2017

@tidoust @mfoltzgoogle tidoust + mfoltzgoogle Issue #396: Migrate HTML 5.0 references to HTML 5.1 (#404)
* Issue #396: Migrate HTML 5.0 references to HTML 5.1

This commit updates all HTML 5.0 references to HTML 5.1.

To help assess references stability (issue #295), the spec now also directly
references the WebIDL Level 1 Recommendation, pointing out that NotAllowedError
is defined in WebIDL Level 2. References to the WHATWG version of HTML for
"current settings object" and "relevant settings object" now target HMTL 5.1
as well.

Other changes introduced in this commit:
- Correct nesting of <a>, <code>, <dfn> to make sure code definitions get
styled in red as expected
- ReSpec now automatically supports aliases such as "start()" for method, so
dropped the now redundant alias definitions.
- Turned references incorrectly marked as informative into normative references
(UUID, cookies, RFCs).

* HTML 5.1 terms moved to a list, () dropped from method references

Addressing @mfoltzgoogle comments on previous commit, the list of HTML 5.1
terms are now defined in a list, sorted by alphabetic order.

Parentheses next to method names now dropped throughout the specification.
4df5120
Contributor

tidoust commented Jan 12, 2017

I believe the Presentation API now references stable published specifications whenever possible.

One remaining open question: can the Presentation API simply reference the latest version of WebIDL, even though it is not in a stable state, or should the Presentation API spec continue to reference both WebIDL Level 1 and WebIDL Level 2 to point out all WebIDL terms used in the spec are defined in Level 1 except NotAllowedError which is defined in WebIDL Level 2?

I'll try to come up with an answer (needed before requesting transition to Proposed Recommendation, not needed for publication as Candidate Recommendation).

Contributor

mfoltzgoogle commented Jan 23, 2017

Can this be closed now @tidoust? All of the sub-tasks have been addressed.

Contributor

tidoust commented Jan 25, 2017

Closing this issue since all updates were made to the spec, see follow-up issue #408 on reference to WebIDL.

tidoust closed this Jan 25, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment