No normative appendices! #548
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Section "Error Processing": - moved to the end of the "Document Conformance Classes" (in conform.html) - passive-voiced "shall" commands rewritten as requirements on user agents - the example of a general error rewritten to refer to the document conformance requirements - it's made explicit that these general error processing rules can be overridden by more specific rules elsewhere in the spec. Section "Clamping values which are restricted to a particular range": - moved to types.html (Basic Data Types and Interfaces chapter) - paragraphs re color and opacity removed, since clamping behavior of those properties is defined in CSS Color - remaining paragraph generalized, with clarifications that * it only applies if more specific rules aren't given elsewhere * it applies to clamping for device capabilities as well as per spec Section "Elliptical Arc Implementation Notes": - the normative section on out-of-range parameters is moved to the Paths chapter implementation notes. - the syntax is updated to use parameter names defined in the chapter, not the mathematical notation defined in the appendix - the remaining sections on arc parameterization and conversion are tidied up to stand alone in the appendix - Equation numbering is made independent of Appendix/section numbering (which was no longer correct). The rest of the "Implementation Notes" section is paths.html is reorganized into logical sections. The contradictory statement that "A non-positive radius value is an error." is removed. (Elsewhere, the spec says to use the absolute value of negative radii, and most browser implementations match; see #324.) Section "Text selection implementation notes": - moved to the end of the "Text selection and clipboard operations" section (in text.html) Section "Printing implementation notes": - moved to the end of "Conforming SVG Viewers" section (in conform.html) Cross-references to these sections have also been updated. Changes appendix entries have been made. Links to PR will need to be updated once a PR is generated.
- Clarify which software the "SVG DOM requires" statements apply to (viewers/interpreters with scripting support). - Make DOM 4 a minimum requirement, with DOM living standard a "should". Note: W3C DOM 4 isn't currently listed in the refs. Would it be better to make the minimum requirement a timepoint in the DOM LS history? - Remove requirement for support of obsolete DOM View spec. - Update the requirement on DOM Level 2 Style to only include interfaces also defined in CSSOM, with full support for CSSOM as a "should" (CSSOM is still WD, but it drops a lot of DOM Style that was never implemented. Alternative would be to list which DOM2 Style interfaces to support.) DOM Level 2 is included as an informative reference - Remove the "Relationship with DOM Level 2 CSS" section. - Add Geometry Interfaces Module Level 1 as a normative ref, since it didn't seem to be included anywhere (despite being referenced in many WebIDL dependencies). Also: fix some alphabetization issues in refs.html. Add changes entries.
In prep for moving the content to the Types chapter.
- Separate out overview paragraphs on reflecting attributes
from specifics on initializing objects to `(none)` initial values.
- Rename the section on initialization to clarify when it applies,
and add new intro paragraph.
- Make it clear that the rules for initializing compound interfaces
are not restricted to those defined in SVG.
(Reintroduce example of DOMRect &
include other numeric primitive numeric types in initialization list.)
- Remove the special rule about `SVGTextContentElement::textLength`
in this section, and replace it with:
* clearer text defining the initial value of the content attribute
* a note in the IDL definition explaining the impact
of the dynamic initial value
- Use proper example formatting for the "for example"
paragraph, add links/clarification,
and add a matching example of initializing a `(none)` value.
Section "Elements in the SVG DOM": - Add a preamble paragraph to clarify normative requirements. - Make it clear that the rule applies to SVG-namespaced elements defined in other specifications (e.g., filters, masking). - Add a requirement for handling unknown elements. (Should implement SVGUnknownElement; must implement SVGElement, since that's what browsers do.) - Add a warning about SVGUnknownElement being at-risk. - Mark up the "for example" as a proper example. Section "Naming Conventions": - Make the naming conventions section reference modern DOM + HTML, and remove the informative reference to DOM Level 1. - Add a paragraph on the naming conventions of interfaces. - Remove mention of (long-since-removed) CDATA type; Case preservation when reflecting strings is already covered by the rules in HTML about reflecting basic types. (and either way, that's not part of Naming Conventions!) Section "Invalid Values": - Clarify that this applies to reflected attributes & validity restrictions on the content attributes. - Add a link to Github Issue #547, re matching reality.
In preparation for merging into the interactivity chapter. - Add a normative reference to the Clipboard API spec, since we're including event handlers for the events it defines. - Add normative wording about which events need to be implemented (with exceptions for non interactive environments, and an exclusion for the legacy events defined in UI Events spec). - Clarify that most onEvent attributes/properties are available on all elements in the SVG namespace. - remove statements and example about onclick, etc. attributes only being valid on certain elements. - Keep the general rule about event attributes not working where invalid (since it applies to & is implemented for onbegin, onend, etc.) But remove statements about addEventListener working, because those events don't support addEventListener, per the table in https://svgwg.org/svg2-draft/interact.html#SVGEvents - Remove a cross-reference to the deleted paragraph from pservers.html - Mark up the example as such.
And re-arrange some content to match.
With additional edits only when required for
merge conflicts with existing content.
In types.html:
- #SVGDOMOverview is now a major section in types.html,
with the following subsections taken from svgdom.html and
from the length intro to
types.html#DOMInterfacesForReflectingSVGAttributes
* Dependencies (new heading for content from svgdom.html)
* Naming conventions (from svgdom.html)
* Elements in the SVG DOM (from svgdom.html)
* Reflecting content attributes in the DOM (merging intros,
with a little extra effort to actually define the term "reflect")
* Synchronizing reflected values
(new heading on content from types.html)
* Reflecting an empty initial value (from svgdom.html)
* Invalid values (from svgdom.html)
- Without its intro section on what reflecting attributes means,
the major section for DOM interfaces that reflect attributes
is renamed to clarify these are the *Animated* interfaces,
with a brief intro about the baseVal/animVal structure.
- The one non-animated interface in that section
(SVGStringList) is moved up to the previous section.
- Elsewhere in types.html, the short sections on
number precision and clamping are made sub-sections
to the attribute syntax.
In interact.html:
- The "Relationship with UI Events" section is inserted as a sub-section
to "Supported Events" except:
- The paragraphs about possible implementation of event attributes,
and the example of their use, is added at the end of the
"Event attributes" section.
- A mention of that section as being in another chapter is removed.
svgdom.html, with its content removed, is turned into a stub file
(and publish.xml updated accordingly)
Cross-references are updated in other files.
Changes section is updated
(including some updates that should have been on the last commit).
AmeliaBR
requested review from
ewilligers,
dirkschulze,
svgeesus and
Tavmjong
September 20, 2018 07:18
svgeesus
reviewed
Sep 20, 2018
svgeesus
reviewed
Sep 20, 2018
svgeesus
reviewed
Sep 21, 2018
AmeliaBR
commented
Sep 21, 2018
|
Thanks for the comments, Chris. Definitely looking for reviews not only of my changes (& making sure I haven't dropped anything), but also of whether additional updates are required to some of the older text that has been lurking in the appendices all this time. |
svgeesus
reviewed
Sep 22, 2018
AmeliaBR
added a commit
that referenced
this pull request
Sep 27, 2018
Point to WHATWG DOM Review Drafts for the "must" link to a stable specification as of the time of our publication, and add an explicit exception for any removed/deprecated features. The "should" requirement still points to the latest DOM LS. As discussed with @svgeesus while reviewing PR #548: #548 (comment)
svgeesus
pushed a commit
that referenced
this pull request
Sep 28, 2018
* Move normative parts of implnote.html to chapters Section "Error Processing": - moved to the end of the "Document Conformance Classes" (in conform.html) - passive-voiced "shall" commands rewritten as requirements on user agents - the example of a general error rewritten to refer to the document conformance requirements - it's made explicit that these general error processing rules can be overridden by more specific rules elsewhere in the spec. Section "Clamping values which are restricted to a particular range": - moved to types.html (Basic Data Types and Interfaces chapter) - paragraphs re color and opacity removed, since clamping behavior of those properties is defined in CSS Color - remaining paragraph generalized, with clarifications that * it only applies if more specific rules aren't given elsewhere * it applies to clamping for device capabilities as well as per spec Section "Elliptical Arc Implementation Notes": - the normative section on out-of-range parameters is moved to the Paths chapter implementation notes. - the syntax is updated to use parameter names defined in the chapter, not the mathematical notation defined in the appendix - the remaining sections on arc parameterization and conversion are tidied up to stand alone in the appendix - Equation numbering is made independent of Appendix/section numbering (which was no longer correct). The rest of the "Implementation Notes" section is paths.html is reorganized into logical sections. The contradictory statement that "A non-positive radius value is an error." is removed. (Elsewhere, the spec says to use the absolute value of negative radii, and most browser implementations match; see #324.) Section "Text selection implementation notes": - moved to the end of the "Text selection and clipboard operations" section (in text.html) Section "Printing implementation notes": - moved to the end of "Conforming SVG Viewers" section (in conform.html) Cross-references to these sections have also been updated. Changes appendix entries have been made. Links to PR will need to be updated once a PR is generated. * Update dependencies in SVG DOM appendix - Clarify which software the "SVG DOM requires" statements apply to (viewers/interpreters with scripting support). - Make DOM 4 a minimum requirement, with DOM living standard a "should". Note: W3C DOM 4 isn't currently listed in the refs. Would it be better to make the minimum requirement a timepoint in the DOM LS history? - Remove requirement for support of obsolete DOM View spec. - Update the requirement on DOM Level 2 Style to only include interfaces also defined in CSSOM, with full support for CSSOM as a "should" (CSSOM is still WD, but it drops a lot of DOM Style that was never implemented. Alternative would be to list which DOM2 Style interfaces to support.) DOM Level 2 is included as an informative reference - Remove the "Relationship with DOM Level 2 CSS" section. - Add Geometry Interfaces Module Level 1 as a normative ref, since it didn't seem to be included anywhere (despite being referenced in many WebIDL dependencies). Also: fix some alphabetization issues in refs.html. Add changes entries. * Reorganize SVGDOM content re initializing values In prep for moving the content to the Types chapter. - Separate out overview paragraphs on reflecting attributes from specifics on initializing objects to `(none)` initial values. - Rename the section on initialization to clarify when it applies, and add new intro paragraph. - Make it clear that the rules for initializing compound interfaces are not restricted to those defined in SVG. (Reintroduce example of DOMRect & include other numeric primitive numeric types in initialization list.) - Remove the special rule about `SVGTextContentElement::textLength` in this section, and replace it with: * clearer text defining the initial value of the content attribute * a note in the IDL definition explaining the impact of the dynamic initial value - Use proper example formatting for the "for example" paragraph, add links/clarification, and add a matching example of initializing a `(none)` value. * More updating of SVGDOM appendix Section "Elements in the SVG DOM": - Add a preamble paragraph to clarify normative requirements. - Make it clear that the rule applies to SVG-namespaced elements defined in other specifications (e.g., filters, masking). - Add a requirement for handling unknown elements. (Should implement SVGUnknownElement; must implement SVGElement, since that's what browsers do.) - Add a warning about SVGUnknownElement being at-risk. - Mark up the "for example" as a proper example. Section "Naming Conventions": - Make the naming conventions section reference modern DOM + HTML, and remove the informative reference to DOM Level 1. - Add a paragraph on the naming conventions of interfaces. - Remove mention of (long-since-removed) CDATA type; Case preservation when reflecting strings is already covered by the rules in HTML about reflecting basic types. (and either way, that's not part of Naming Conventions!) Section "Invalid Values": - Clarify that this applies to reflected attributes & validity restrictions on the content attributes. - Add a link to Github Issue #547, re matching reality. * Update UI Events section in SVGDOM appendix In preparation for merging into the interactivity chapter. - Add a normative reference to the Clipboard API spec, since we're including event handlers for the events it defines. - Add normative wording about which events need to be implemented (with exceptions for non interactive environments, and an exclusion for the legacy events defined in UI Events spec). - Clarify that most onEvent attributes/properties are available on all elements in the SVG namespace. - remove statements and example about onclick, etc. attributes only being valid on certain elements. - Keep the general rule about event attributes not working where invalid (since it applies to & is implemented for onbegin, onend, etc.) But remove statements about addEventListener working, because those events don't support addEventListener, per the table in https://svgwg.org/svg2-draft/interact.html#SVGEvents - Remove a cross-reference to the deleted paragraph from pservers.html - Mark up the example as such. * Move SVGDOM appendix content to chapters And re-arrange some content to match. With additional edits only when required for merge conflicts with existing content. In types.html: - #SVGDOMOverview is now a major section in types.html, with the following subsections taken from svgdom.html and from the length intro to types.html#DOMInterfacesForReflectingSVGAttributes * Dependencies (new heading for content from svgdom.html) * Naming conventions (from svgdom.html) * Elements in the SVG DOM (from svgdom.html) * Reflecting content attributes in the DOM (merging intros, with a little extra effort to actually define the term "reflect") * Synchronizing reflected values (new heading on content from types.html) * Reflecting an empty initial value (from svgdom.html) * Invalid values (from svgdom.html) - Without its intro section on what reflecting attributes means, the major section for DOM interfaces that reflect attributes is renamed to clarify these are the *Animated* interfaces, with a brief intro about the baseVal/animVal structure. - The one non-animated interface in that section (SVGStringList) is moved up to the previous section. - Elsewhere in types.html, the short sections on number precision and clamping are made sub-sections to the attribute syntax. In interact.html: - The "Relationship with UI Events" section is inserted as a sub-section to "Supported Events" except: - The paragraphs about possible implementation of event attributes, and the example of their use, is added at the end of the "Event attributes" section. - A mention of that section as being in another chapter is removed. svgdom.html, with its content removed, is turned into a stub file (and publish.xml updated accordingly) Cross-references are updated in other files. Changes section is updated (including some updates that should have been on the last commit). * Remove link to DOM 4 in required dependencies Point to WHATWG DOM Review Drafts for the "must" link to a stable specification as of the time of our publication, and add an explicit exception for any removed/deprecated features. The "should" requirement still points to the latest DOM LS. As discussed with @svgeesus while reviewing PR #548: #548 (comment) * Update changes re PR #548 To add links to the PR & related issue #520. Closes #520.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Following the discussion in #520, this PR:
This is a lot of change, and some of it is important normative content!
I highly recommend reviewing it commit by commit, so you can separate the updates from the relocations. Unfortunately, git is not very good at tracking the same content moved to different places.
Before merging, the changes entries need to be updated to include links to this PR.
There may also need to be some careful merging with PR #544 to not miss anything that's moved around.