[go: up one dir, main page]

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update/move the normative-but-outdated SVG DOM appendix #520

Closed
AmeliaBR opened this issue Aug 9, 2018 · 11 comments
Closed

Update/move the normative-but-outdated SVG DOM appendix #520

AmeliaBR opened this issue Aug 9, 2018 · 11 comments

Comments

@AmeliaBR
Copy link
Contributor
AmeliaBR commented Aug 9, 2018

As I'm reviewing & tidying the changes appendix, I discovered we still have a normative "SVG DOM" appendix, which is in need of updates.

Required fixes include:

  • Updating cross-references (e.g., to CSSOM, not DOM2 CSS).
  • Clarify which parts are informative summaries of content normatively defined elsewhere.
  • Redefine the section on initializing properties in a WebIDL consistent way (or remove, if the WebIDL definitions elsewhere already cover this).
  • Check whether some of the specific behaviors actually match implementations:
    • Manually dispatched events on elements that don't normally receive events (I don't think we actually disallow event attributes on non-rendered elements, do we?)
    • Invalid values behavior

I suggest also:

I don't like having normative appendices, and one reason is they get overlooked and out of date! Once we fix this one, the only other normative appendix is Implementation Requirements. I'd prefer to move its content into the relevant chapters, too, but at least it had a very "Hi, I'm Normative" nametag.

@svgeesus
Copy link
Contributor

The Implementation Requirements appendix started as somewhere convenient to park the lengthy mathematical derivation of the elliptical arc decomposition, which was done by Phillip Mansfield so that the last point of the command could be the current point of the next command (same as all the other path commands).

I agree that some of the other parts are easy to overlook. At minimum they should be well crosslinked from other parts of the spec; it might be a good idea to move some parts to the main spec. For example Clamping Values might usefully move to Basic Data Types?

@AmeliaBR
Copy link
Contributor Author
AmeliaBR commented Aug 20, 2018

somewhere convenient to park the lengthy mathematical derivation of the elliptical arc decomposition

I agree that the conversion algorithms are appropriate for an appendix, because they aren't normative: they're just helpful notes for implementers. Similarly, the new "Notes on generating high-precision geometry" section is informative. They could stay in the appendix and it could be renamed "Implementation Notes".

For the rest:

  • Error processing could go in Conformance Criteria.

  • I agree, that Clamping Values makes sense in Basic Data Types.

  • The normative bits about elliptical arc syntax and out-of-range parameters should be moved to the paths chapter. We already have an Implementation notes section with error handling details.

  • The text selection implementation notes could go into either the text or interactivity chapters.

  • The "Printing implementation notes" aren't normative, so they could stay in the appendix, too. But the section is short enough that it could also go into the "SVG Viewers" section of Conformance Criteria as a green note-box.

@dirkschulze dirkschulze self-assigned this Aug 20, 2018
@css-meeting-bot
Copy link
Member

The Working Group just discussed Update/move the normative-but-outdated SVG DOM appendix, and agreed to the following:

  • RESOLUTION: Move normative text from appendixes to chapters. Discuss particular moves in the issues.
The full IRC log of that discussion <krit> topic: Update/move the normative-but-outdated SVG DOM appendix
<krit> github: https://github.com//issues/520
<krit> AmeliaBR: title is specifically about SVGDOM appendix but it actually is normative text. Other normative text is implementation requirement.
<krit> AmeliaBR: one issue with the SVG DOM appendix: It is not very up-to-date. Not all spec references are the latest version of the spec. So some editing is needed.
<krit> AmeliaBR: Do we want to bring normative text out of appendix and merge it into main sections.
<krit> krit: wasn't there a lot of normative text?
<krit> AmeliaBR: not anymore.
<krit> krit: we are just talking about normative text that is no implementation requirement first?
<krit> AmeliaBR: everything that is required... some parts are simple notes
<krit> AmeliaBR: I looked where the different implementation reuiqremnts could go. SVG DOM probably in scripting.
<krit> AmeliaBR: First step: do we want to move content into the chapters.
<krit> krit: Fine with specific normative text. What about cross-section normative text?
<krit> AmeliaBR: we have some sections that are cross sections. We could put the text there.
<krit> Tav: Getting it out of the end might be a good idea.
<krit> Tav: like crapping values that clip to a certain range. I think there are even issues in filters because of this.
<krit> krit: sounds like there is an agreement
<krit> RESOLUTION: Move normative text from appendixes to chapters. Discuss particular moves in the issues.
<AmeliaBR> s/crapping/clamping/
<krit> AmeliaBR: need some volunteer to update the references and see where text can move.
<krit> krit: I can volunteer for taking a first look and lining out suggestions

@AmeliaBR
Copy link
Contributor Author

@dirkschulze Do you think you could get to these edits this week, so it could be included in a republication with the chapter stubs? (#542)

(Also: when you do make the edits, be sure to leave a stub file for svgdom.html. And maybe a note in the informative implnote.html pointing to where the normative bits have been moved.)

@AmeliaBR AmeliaBR assigned AmeliaBR and unassigned dirkschulze Sep 17, 2018
@AmeliaBR
Copy link
Contributor Author

Looking closer at the section on clamping values, I think this should either be dropped completely or significantly rewritten.

Rules about clamping color component values and opacity values are now defined in CSS Color. (And, quite frankly, the SVG 1 wording isn't very clear to start with, relying on vague phrases like "at the time which opacity values have to be processed".)

Most other properties where clamping is relevant should have the clamping behavior defined as part of the property definition.

For now, I'll probably leave in a one-paragraph general rule: "Where not otherwise specified…" clamping should happen as late as possible. That way, there is no normative change in case of any properties or attributes which don't have their own detailed rules.


For reference, the existing text is as follows:

Clamping values which are restricted to a particular range

Some numeric attribute and property values have restricted ranges, such as color component values. When out-of-range values are provided, the user agent shall defer any error checking until after presentation time, as composited actions might produce intermediate values which are out-of-range but final values which are within range.

Color values are not in error if they are out-of-range, even if final computations produce an out-of-range color value at presentation time. It is recommended that user agents clamp color values to the nearest color value (possibly determined by simple clipping) which the system can process as late as possible (e.g., presentation time), although it is acceptable for user agents to clamp color values as early as parse time. Thus, implementation dependencies might preclude consistent behavior across different systems when out-of-range color values are used.

Opacity values out-of-range are not in error and should be clamped to the range 0 to 1 at the time which opacity values have to be processed (e.g., at presentation time or when it is necessary to perform intermediate filter effect calculations).

@AmeliaBR
Copy link
Contributor Author

The "Printing implementation notes" aren't normative,

On re-reading, I decided that actually, they are written as normative text, albeit as "should" not "must". I've kept them as normative while moving to the Conformance Criteria chapter.

@AmeliaBR
Copy link
Contributor Author

For the spec dependencies currently listed in the SVG DOM appendix, these are the updates I'm making:

  • 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).

@AmeliaBR
Copy link
Contributor Author

One more new normative reference: Clipboard APIs, since we've already added all the event handler attributes/properties for the events it defines.

@AmeliaBR
Copy link
Contributor Author

Re:

Check whether some of the specific behaviors actually match implementations:

  • Manually dispatched events on elements that don't normally receive events (I don't think we actually disallow event attributes on non-rendered elements, do we?)

No, we don't, we now allow them on all elements, except for the animation-specific attributes (which have their own quirks and limitations).

  • Invalid values behavior

Well, this one was a mess. I filed #547 & added a tracking issue to the spec.

Massive PR coming up momentarily…

@svgeesus
Copy link
Contributor

@AmeliaBR do we need this issue open for any tidying, or does the big PR mean we can close it? (I think it can be closed).

@css-meeting-bot
Copy link
Member

The SVG Working Group just discussed Move Normative Appendices.

The full IRC log of that discussion <AmeliaBR> Topic: Move Normative Appendices
<AmeliaBR> github: https://github.com//issues/520
<AmeliaBR> Chris: Can this be closed now?
<stakagi> no
<AmeliaBR> Amelia: I have a couple tidy-up commits to do that didn't make it into the merged PR, but I should close it today or tomorrow.

AmeliaBR added a commit that referenced this issue Sep 27, 2018
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
Projects
None yet
Development

No branches or pull requests

4 participants