Editorial: Consistify prose for same-value properties #2575

jmdyck · 2021-11-10T03:44:10Z

Use consistent prose when the initial values of two intrinsic-properties are the same object.

spec.html

michaelficarra · 2021-11-11T00:14:00Z

Within this PR, we are still inconsistent about whether we refer to just the property name (keys/@@iterator/trimLeft/trimRight) or we refer to its whole position (Date.prototype.toGMTString/Number.parseInt/Number.parseFloat). I think that should be made consistent as well.

jmdyck · 2021-11-11T02:07:47Z

Within this PR, we are still inconsistent about whether we refer to just the property name (keys/@@iterator/trimLeft/trimRight) or we refer to its whole position (Date.prototype.toGMTString/Number.parseInt/Number.parseFloat). I think that should be made consistent as well.

I agree, but that inconsistency is much wider than the few spots addressed by this PR, so I was going to deal with it separately. In fact, I'll open an issue to start the discussion.

gibson042

Should this also align the rest of the variants?

$ grep -o 'initial value of .* property' spec.html | \
  sed 's/property.*/property/; s/[*]"[^*"]*"[*]/*"…"*/; s/@@[[:graph:]]*/@@…/' | \
  sort | uniq -c
      1 initial value of the async generator function's *"…"* property
      1 initial value of the @@… data property
      1 initial value of the function's `name` property
      1 initial value of the function's *"…"* property
      1 initial value of the generator function's *"…"* property
     31 initial value of the @@… property
     40 initial value of the *"…"* property
      1 initial value of the %TypedArray%`.prototype.toString` data property

I'm thinking it would involve replacing «@@… data property» with «@@… property» and «function's `name` property» with «function's *"name"* property» (the other «[$type] function's *"…"* property» patterns refer to prototype initialization and seem fine to me).

gibson042 · 2021-11-11T02:43:15Z

spec.html

@@ -47397,7 +47397,7 @@ <h1>Date.prototype.toGMTString ( )</h1>
        <emu-note>
          <p>The `toUTCString` method is preferred. The `toGMTString` method is provided principally for compatibility with old code.</p>
        </emu-note>
-        <p>The function object that is the initial value of `Date.prototype.toGMTString` is the same function object that is the initial value of `Date.prototype.toUTCString`.</p>
+        <p>The initial value of the `Date.prototype.toGMTString` property is %Date.prototype.toUTCString%, defined in <emu-xref href="#sec-date.prototype.toutcstring"></emu-xref>.</p>


Suggested change

The initial value of the `Date.prototype.toGMTString` property is %Date.prototype.toUTCString%, defined in <emu-xref href="#sec-date.prototype.toutcstring"></emu-xref>.

The initial value of the *"toGMTString"* property is %Date.prototype.toUTCString%, defined in <emu-xref href="#sec-date.prototype.toutcstring"></emu-xref>.

Whether to use the "full name" or just the property key is the same point that @michaelficarra brought up. Again, I'd like to defer that to a bigger PR (after some discussion about what's wanted).

I agree in general, but in this specific case I think it makes sense to match the nearby sections right now (specifically the preceding String.prototype.trimLeft and String.prototype.trimRight, which this PR updates to «The initial value of the *"trim{Left,Right}"* property is…»).

I agree with @gibson042. While it's true that there's lots of other inconsistency remaining to be fixed, it is also true that as of this PR there are 44 uses of precise phrase "The initial value of the X property", and of them only Number.parseFloat, Number.parseInt, %TypedArray%`.prototype.toString`, and Date.prototype.toGMTString are written out as full paths, and all of those uses are introduced by this PR. Seems best to just make those four consistent with the other uses of that phrase for the moment, and possibly change them all as part of #2576.

Hm. Maybe I'll just pause this PR until #2576 makes some progress on question (1).

Ehhh, I'd prefer to just land this, with the specific inconsistency mentioned above fixed, and then deal with #2576 later. I'm happy to push up a commit to this branch addressing the above comment if you'd prefer not to do it yourself.

Nah, you wore me down. I'll push a commit.

gibson042 · 2021-11-11T02:46:33Z

spec.html

@@ -39220,7 +39220,7 @@ <h1>%TypedArray%.prototype.toLocaleString ( [ _reserved1_ [ , _reserved2_ ] ] )<

      <emu-clause id="sec-%typedarray%.prototype.tostring">
        <h1>%TypedArray%.prototype.toString ( )</h1>
-        <p>The initial value of the %TypedArray%`.prototype.toString` data property is the same built-in function object as the `Array.prototype.toString` method defined in <emu-xref href="#sec-array.prototype.tostring"></emu-xref>.</p>
+        <p>The initial value of the %TypedArray%`.prototype.toString` property is %Array.prototype.toString%, defined in <emu-xref href="#sec-array.prototype.tostring"></emu-xref>.</p>


Suggested change

The initial value of the %TypedArray%`.prototype.toString` property is %Array.prototype.toString%, defined in <emu-xref href="#sec-array.prototype.tostring"></emu-xref>.

The initial value of the *"toString"* property is %Array.prototype.toString%, defined in <emu-xref href="#sec-array.prototype.tostring"></emu-xref>.

The initial value of the *"toGMTString"* property is %Date.prototype.toUTCString%, defined in .

jmdyck · 2021-11-11T03:32:28Z

Should this also align the rest of the variants?

If by "this" you mean "this PR", then no, I intentionally made this PR very narrowly scoped. But yes, I'd like those variants to be made consistent, and I'll do the job if I can get a sense of how the editors would like things aligned. See Issue #2576.

$ grep -o 'initial value of .* property' spec.html | ...

Note that that doesn't find all variants, because some don't use the word "initial" and some don't use the word "value" and some don't use the word "property".

michaelficarra

It's an improvement, and I'm looking forward to your PR that further refines this phrasing.

Use consistent prose when the initial values of two intrinsic-properties are the same object. In the sentences affected by this PR, refer to properties by just the final property name rather than by "full paths". That is, change: - `Number.parseFloat` to *"parseFloat"* - `Number.parseInt` to *"parseInt"* - %TypedArray%`.prototype.toString` to *"toString"* - `Date.prototype.toGMTString` to *"toGMTString"* This increases consistency among sentences of this particular form. (But note that they're a small fraction of a large class of sentences being considered by issue tc39#2576, whose resolution could 'overturn' this choice, or other choices made in this PR)

jmdyck added the editorial change label Nov 10, 2021

ljharb reviewed Nov 10, 2021

View reviewed changes

spec.html Outdated Show resolved Hide resolved

ljharb requested review from syg, michaelficarra, bakkot and a team November 10, 2021 16:55

jmdyck mentioned this pull request Nov 11, 2021

Editorial: inconsistent prose for intrinsics #2576

Closed

gibson042 approved these changes Nov 11, 2021

View reviewed changes

michaelficarra approved these changes Nov 11, 2021

View reviewed changes

jmdyck force-pushed the same-value-properties branch from 76ef273 to 12d1e95 Compare November 13, 2021 22:49

bakkot approved these changes Nov 13, 2021

View reviewed changes

bakkot added the ready to merge Editors believe this PR needs no further reviews, and is ready to land. label Nov 16, 2021

ljharb force-pushed the same-value-properties branch from 12d1e95 to e06c80c Compare November 18, 2021 07:19

ljharb merged commit e06c80c into tc39:main Nov 18, 2021

jmdyck deleted the same-value-properties branch November 18, 2021 21:56

bakkot added the establishes editorial conventions label Jan 31, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Editorial: Consistify prose for same-value properties #2575

Editorial: Consistify prose for same-value properties #2575

Uh oh!

jmdyck commented Nov 10, 2021

Uh oh!

Uh oh!

michaelficarra commented Nov 11, 2021

Uh oh!

jmdyck commented Nov 11, 2021

Uh oh!

gibson042 left a comment •

edited

Loading

Uh oh!

gibson042 Nov 11, 2021

Uh oh!

jmdyck Nov 11, 2021

Uh oh!

gibson042 Nov 11, 2021

Uh oh!

bakkot Nov 13, 2021

Uh oh!

jmdyck Nov 13, 2021

Uh oh!

bakkot Nov 13, 2021 •

edited

Loading

Uh oh!

jmdyck Nov 13, 2021

Uh oh!

gibson042 Nov 11, 2021

Uh oh!

jmdyck commented Nov 11, 2021

Uh oh!

michaelficarra left a comment

Uh oh!

Uh oh!

	<p>The initial value of the `Date.prototype.toGMTString` property is %Date.prototype.toUTCString%, defined in <emu-xref href="#sec-date.prototype.toutcstring"></emu-xref>.</p>
	<p>The initial value of the "toGMTString" property is %Date.prototype.toUTCString%, defined in <emu-xref href="#sec-date.prototype.toutcstring"></emu-xref>.</p>

	<p>The initial value of the %TypedArray%`.prototype.toString` property is %Array.prototype.toString%, defined in <emu-xref href="#sec-array.prototype.tostring"></emu-xref>.</p>
	<p>The initial value of the "toString" property is %Array.prototype.toString%, defined in <emu-xref href="#sec-array.prototype.tostring"></emu-xref>.</p>

Editorial: Consistify prose for same-value properties #2575

Editorial: Consistify prose for same-value properties #2575

Uh oh!

Conversation

jmdyck commented Nov 10, 2021

Uh oh!

Uh oh!

michaelficarra commented Nov 11, 2021

Uh oh!

jmdyck commented Nov 11, 2021

Uh oh!

gibson042 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gibson042 Nov 11, 2021

Choose a reason for hiding this comment

Uh oh!

jmdyck Nov 11, 2021

Choose a reason for hiding this comment

Uh oh!

gibson042 Nov 11, 2021

Choose a reason for hiding this comment

Uh oh!

bakkot Nov 13, 2021

Choose a reason for hiding this comment

Uh oh!

jmdyck Nov 13, 2021

Choose a reason for hiding this comment

Uh oh!

bakkot Nov 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmdyck Nov 13, 2021

Choose a reason for hiding this comment

Uh oh!

gibson042 Nov 11, 2021

Choose a reason for hiding this comment

Uh oh!

jmdyck commented Nov 11, 2021

Uh oh!

michaelficarra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gibson042 left a comment •

edited

Loading

bakkot Nov 13, 2021 •

edited

Loading