search

WebAudio / web-audio-api

The Web Audio API v1.0, developed by the W3C Audio WG
https://webaudio.github.io/web-audio-api/
Other
1.05k stars 166 forks source link

Fix #2361: Use new Web IDL buffer primitives #2363

Closed rtoy closed 3 years ago

rtoy commented 3 years ago

Updates spec to use new Web IDL buffer primitives. The changes are marked as candidate corrections, but we use several correction amendments to make it easy to see what the new and old text will be. Using just one makes it super-hard to figure out what controls the text, and the text sometimes doesn't always clearly show what's deleted and what's inserted because the links are colored correctly, and struck-through text doesn't strike through links. (A bikeshed issue?)

Preview | Diff

rtoy commented 3 years ago

Biekshed has been updated to include the WebIDL references that were previously failing in https://travis-ci.com/github/WebAudio/web-audio-api/builds/230909490.

However, the link for "get a reference to the buffer source" is now no longer part of WebIDL, I think that means we should just remove the link for the <del> part since it doesn't work.

rtoy commented 3 years ago

See #2366 for an example of adding previous and next buttons in each amendment box so it's easy to navigate each of the related changes. This won't show up in the preview. You'll have to build it yourself to see.

rtoy commented 3 years ago

Previous and Next buttons added. The JS code is now inline, so the preview shows the buttons and also the generated list of amendments for the changelog.

I'd appreciate help in getting the JS code nicer. This was just something I hacked together that worked for this case.

rtoy commented 3 years ago

Also, take a look at https://pr-preview.s3.amazonaws.com/rtoy/web-audio-api/pull/2367.html#c2361-1 where the amendment box is scoped to include all the changes for the change. Works nicely for paragraphs, but for algorithms, I think the box needs to be around all the steps in the algorithm, so the box scope can be pretty big, as shown in 2361-1.

Alternatively, we could maybe just add amendment boxes in each step, since we're keeping track of related changes.

rtoy commented 3 years ago

See https://pr-preview.s3.amazonaws.com/rtoy/web-audio-api/pull/2368.html#c2361-1 for an example where we restrict the scope of a change the the smallest reasonable block. This is kind of nice when the changes occur in an algorithm block so we don't include the entire algorithm in the scope of the change block.

I find having the scope of the changed marked out being pretty nice, especially for algorithms since it can be hard to know where the change would end.

rtoy commented 3 years ago

Oh, according to https://fantasai.inkedblade.net/style/design/w3c-restyle/2020/readme#proposed-changes, the changes should be marked as proposed corrections/additions.

rtoy commented 3 years ago

Merged in the proposals from #2367 and #2368 into this. Now the boxes include the changed text area and each box covers a smaller change, such as a paragraph or one step in an algorithm.

Also updated the buttons to say "Previous Change" and "Next Change" to make it easier to understand the the previous/next buttons really did.

hoch commented 3 years ago

I think we can merge this.