Rename Range's 'start' and 'end' to 'range start' and 'range end'.

[tabatkins]

https://dom.spec.whatwg.org/#concept-range-start

A range has two associated boundary points — a start and end.

These definitions are correctly namespaced, but the words are still pretty generic, which has two problems:

• It's so generic, it makes some of the more complex sentences in the DOM spec harder to read because the association of these words to the range object is implicit rather than immediately obvious.
• It conflicts with other uses of [=start=] and [=end=], such as the (much more common) usage of CSS's "start" and "end" directions, which then always need to specify [=CSS/start=]. (There are other definitions of plain "start"/"end" in Bikeshed's db also, but none of them are exported so they don't interfere.)

Would you mind renaming to "range start" and "range end"? This would also simplify your markup a bit - right now every usage of the terms is written as <a for=range>start</a>; after this fix they'd be [=range start=]. This PR does so, and I believe is an editorial improvement.

---

Preview | Diff

[annevk]

I'm sorry, but this seems wrong. Fields shouldn't contain the name of the concept they belong to. I'm not sure how these are used in CSS, but presumably there they would also belong to something?

[tabatkins]

Would you prefer the term "start/end point", then, since they are naming boundary points?

[fantasai]

@annevk They're used primarily as adjectives in the CSS specs.

[tabatkins]

Yeah, in CSS it's like "the start side", "in the startmost direction", etc. They're just directions, and don't belong to any one concept (thus the current for=CSS we have on the dfns).

[domenic]

(IIUC, cases like this are why I prefer the "explicit for" Bikeshed option...)

[domenic]

A potential solution for the CSSWG here is to add a link-defaults block to their shared Bikeshed template, preferring CSS terms over any conflicts.

[fantasai]

@domenic I would be glad to have CSS configured to prefer its own terms internally somehow if that's possible; @tabatkins is that possible? (Splitting into modules is useful to us in a lot of ways but it definitely makes cross-linking more of a mess.)

That said, I do think the DOM spec would be easier to read if the “start” and “end” concepts were a bit more specific, regardless, though, so maybe we can do both? At least I found things easier to read when reviewing the built results of the patch here, and I suspect Tab's follow-up suggestion of using “start point” and “end point” would have a similar effect. The extra word helps anchor it as a technical term referring to a particular data member, rather than as its more general English usage.

[annevk]

I think the cases where it might help readability are due to a bug. There's a number of places such as https://dom.spec.whatwg.org/#dom-range-selectnodecontents that really ought to say "this's start" but instead just say "start".

[tabatkins]

Fields shouldn't contain the name of the concept they belong to.

I don't think this is at all universal - we often put the parent term into sub-definitions, for readability. We'll often put in a local-lt without the prefix, so it's not too repetitious in the spec itself, which is most likely to say it a bunch and have the context already, but that's it.

I would be glad to have CSS configured to prefer its own terms internally somehow if that's possible; @tabatkins is that possible? (Splitting into modules is useful to us in a lot of ways but it definitely makes cross-linking more of a mess.)

It's not currently possible; it would require some categorization and logic that does not exist currently. Probably something I want eventually, but still needs a lot of thought to make it more than just "something for the CSSWG to use".

[domenic]

It's not currently possible; it would require some categorization and logic that does not exist currently. Probably something I want eventually, but still needs a lot of thought to make it more than just "something for the CSSWG to use".

I don't understand. Can't you just add

<pre class=link-defaults>
spec:css-writing-modes-4; type:dfn; text:start
</pre>

to the CSSWG template, e.g. in https://github.com/speced/bikeshed-boilerplate/blob/main/boilerplate/csswg/abstract.include ?

[tabatkins]

I was responding to the request for a more general "prefer CSS terms".

[fantasai]

"this's start" but instead just say "start"

That... only helps somewhat. :) I know that it's completely unambiguous when you focus hard on the words and force your brain to interpret them as technical terms referring to particular data points, but they're such generic terms that it takes extra mental effort to do that. (At least for me, as someone who doesn't spend as much time in the DOM spec.) I do think either the original PR or using Tab's suggestion of “start point” and “end point” would help here.

Like, this is easy for me to parse, because “start node” is clearly a term referring to a bit of data:

For each live range whose start node is parent and start offset is greater than child’s index, increase its start offset by count.

but this one is hard, because it's not immediately obvious what kind of thing “start” is:

Set this’s start to (init["startContainer"], init["startOffset"]) and end to (init["endContainer"], init["endOffset"]).

---

Can't you just

If that works, then using that to solve the disambiguation issue sounds reasonable to me, and I'd be in favor of doing it anyway to avoid any future problems. (Still leaves the readability aspect for the DOM spec itself, though.)

---

Fields shouldn't contain the name of the concept they belong to.

I don't think this is at all universal - we often put the parent term into sub-definitions, for readability. We'll often put in a local-lt without the prefix, so it's not too repetitious in the spec itself, which is most likely to say it a bunch and have the context already, but that's it.

Right, we do this a lot in the CSS specs: it gives flexibility within the spec to include more or less context into the term depending on how much context is needed in that particular instance of use, and also with not exporting overly-generic terms--which helps with avoiding conflicts, but also with readability by including more context into the linking term when it's used from the outside. Like, I would really like to be able to link “URL fragment” as a term; “fragment” by itself is too vague in a lot of sentences. :/

[tabatkins]

[=fragment=] by itself is too vague in a lot of sentences. :/

Right, [=URL/fragment=] can be too vague, URL [=URL/fragment=] repeats the term in the source code (annoying) and shrinks the linkified area, [=URL/fragment|URL fragment=] is more repetition but a better linked term.

But [=URL fragment=] is often just right, as can be |myUrl|'s [=URL/fragment=] - the point is that the useful level of detail is context dependent, and it's convenient to have the option for the longer one that carries its context with it.

[annevk]

"url/fragment" standalone would be incorrect usage. It's a member of the URL concept. It might make sense to have a standalone "URL fragment" concept, but it would be something else (perhaps what "url/fragment" contains). We try to be quite careful about these things.

[fantasai]

@annevk I have no idea what your last comment means. :/

In any case, @tabatkins @annevk can we move forward here by:

• Taking Domenic's suggestion to include start/end link-defaults in the CSSWG Bikeshed templates and
• Taking Tab's suggestion to rename start/end to “start point” and “end point” in the DOM spec (and recast/merge this PR accordingly)?

If we can do both of these things I think both the CSS and DOM specs’ situations will have improved.