Editorial: modernize TextTrack members

[annevk]

---

/acknowledgements.html ( diff )
/media.html ( diff )

[nigelmegitt]

Comment applies to this line and also to the other getters and setters modified in this PR:

It's unclear what "this's text track's kind" means in this context. Should it be "this text track's kind"? Or more likely "this's kind", given that this is effectively the text track instance, i.e. it's a text track IDL value, and that this would match the other uses of "this's" elsewhere in the spec?

[annevk]

this is the object which holds a text track. Made it more explicit now.

[nigelmegitt]

This is super confusing. Surely the TextTrack object is the representation of a text track?

I read this as saying:

---
  config:
    class:
      hideEmptyMembersBox: true
---
classDiagram
Media Element "1" --> "*" TextTrack
TextTrack "1" --> "1" text track

Loading

However step 2 of the algorithm that immediately follows, for addTextTrack, says that the text track corresponds to the new TextTrack object constructed in step 1. That's the only place where that TextTrack object is assigned some relationship to the text track being added.

Suggested change

	<p>A <code>TextTrack</code> object has an associated <dfn data-x="TextTrack text track"
	for="TextTrack">text track</dfn> (a <span>text track</span>).</p>
	<p>A <code>TextTrack</code> object has a corresponding <dfn data-x="TextTrack text track"
	for="TextTrack">text track</dfn> (a <span>text track</span>).</p>

I get the formal correctness here when there's a "A has B" relationship, but that doesn't seem right here.

(aside: plus it's horrible to read the following sections that have the "this's text track's XYZ" construct when "this" is a TextTrack)

Somehow this situation is avoided with other interfaces, e.g. media, where instead we have the more readable (e.g.) "this's current playback position" and not "This's media resource's current playback position". Similarly the getter for media.volume is simply "this's playback volume".

It's a different scenario for TimeRanges that clearly has a list of time ranges called "ranges", so "this's ranges's size" makes sense.

I'm making the distinction between a direct one to one correspondence, for TextTrack, and an "ownership" relationship (for TimeRanges) and thinking that when there's a direct correspondence, as here, we should be able to make the text more readable without loss of correctness.

[annevk]

This is not changing anything though. This is just making the existing text more explicit. It does seem like we could maybe flatten this as the specification claims they are 1:1.

[annevk]

This would have to be a follow-up change as WebVTT references text track as well.