Make minor grammar corrections/updates #1612

jchue · 2019-11-18T00:56:17Z

Namely in the Async section

CLAassistant · 2019-11-18T00:58:15Z

All committers have signed the CLA.

iliakan · 2019-11-30T07:01:13Z

There should be a space before dashes that you propose, such as methods—.
Also I'm not sure about moving punctuation signs inside of quotes.

@paroche could you please review that?

paroche · 2019-11-30T08:39:50Z

Yes, space also before dash, There is a style which has no spaces on either side, and a style with spaces on both sides. For instance, newspapers that follow the AP style have spaces on both sides. That's what I favor in general.

Here:
The script is executed "asynchronously", as it starts loading now, but runs later, when the function has already finished.
The script is executed "asynchronously," as it starts loading now but runs later when the function has already finished.

It does seem to be the case that in American-style writing the commas go inside quotes, so the change would be "right", though I'm not a fan of that rule.
https://www.thepunctuationguide.com/quotation-marks.html

Are a lot of changes here, some OK, some not. Kind of hard to comment on the whole thing. But oh well....

Here we did it in loadScript, but of course, it's a general approach.
Here we did it in loadScript, but of course it's a general approach.

Change is an improvement. Or could say "but, of course, it's...".

How can we load two scripts sequentially: the first one, and then the second one after it?
How can we load two scripts sequentially: the first one and then the second one after it?

I don't think this is particularly an improvement. It's a matter of taste. I prefer the original.

In the above examples we didn't consider errors. What if the script loading fails? Our callback should be able to react on that.
In the above examples, we didn't consider errors. What if the script loading fails? Our callback should be able to react to that.

I think it's better w/out the comma (1st change). But definitely, "to" is better than "on".

Also, the functions named step* are all of single use, they are created only to avoid the "pyramid of doom." No one is going to reuse them outside of the action chain. So there's a bit of namespace cluttering here.
Also, the functions named step* are all of single use— they are created only to avoid the "pyramid of doom." No one is going to reuse them outside of the action chain. So there's a bit of namespace cluttering here.

Either a space before the dash, or use a semicolon (";").

_1. A "producing code" that does something and takes time. For instance, a code that loads the data over a network. That's a "singer".
2. A "consuming code" that wants the result of the "producing code" once it's ready. Many functions may need that result. These are the "fans".

A "producing code" that does something and takes time. For instance, a code that loads the data over a network. That's a "singer."
A "consuming code" that wants the result of the "producing code" once it's ready. Many functions may need that result. These are the "fans."_

Having commas and periods inside the quotes is the American style. So yes to the changes. (My understanding is that the Brits put the ending punctuation outside the quotes, which I think is more logical). I don't love that rule and it looks especially weird to me when it's only one word in quotes, but that does seem to be the way it is.

That is, .then handler in line (*) now returns new Promise, that becomes settled only after the call of resolve(githubUser) in setTimeout (**).
That is, the .then handler in line (*) now returns new Promise that becomes settled only after the call of resolve(githubUser) in setTimeout (**). The next .then in the chain will wait for that.

Yes to the "the" before .then. But I prefer keeping the comma after new Promise.

Promise.all takes an array of promises (it technically can be any iterable, but is usually an array) and returns a new promise.
Promise.all takes an array of promises (it technically can be any iterable but is usually an array) and returns a new promise.

I like it better with the comma, though it's correct either way.

A bigger example with fetching user information for an array of GitHub users by their names (we could fetch an array of goods by their ids, the logic is identical):
A bigger example with fetching user information for an array of GitHub users by their names (We could fetch an array by their IDs, and the logic would be identical.):

I'm not really in favor of either change.

For example, loadCached function below fetches a URL and remembers (caches) its content. For future calls with the same URL it immediately gets the previous content from cache, but uses Promise.resolve to make a promise of it, so that the returned value is always a promise:
For example, the loadCached function below fetches a URL and remembers (caches) its content. For future calls with the same URL, it immediately gets the previous content from cache but uses Promise.resolve to make a promise of it, so the returned value is always a promise:

I prefer keeping the comma. Slightly better without 'that'.

For everything not mentioned, I'm OK with the changes, or at least somewhat neutral. Or, I didn't notice them.

iliakan · 2019-11-30T11:28:09Z

@paroche thanks, so do we stick to "...," style? There are many other places in the tutorial, I think, where I used "...",

As I got it, we require spaces around a dash.

Any other changes we require PR author to make? Or we just take nothing from it and close it?

Also, when you'd like to correct an exact sentence, there's a way in GitHub to do that, probably you know, the "plus" sign that appears here:

And then "Review" button in the upper-right corner allows to request changes.

paroche · 2019-11-30T22:05:13Z

I would not really want to see you change all the ".....", s to ".....," s. That is considered a rule in American usage but I think it's stupid, and despite many years of reading English it still looks strange to me. It is apparently (I've read) a holdover from manual typesetting when it helped keep the little commas and periods from falling off the plate. So I think it would be fine to stick with the British style for this, at least for lists of quoted items and the like: 'The boxes I see are labeled "red", "green", and "blue", but I think somewhere there's one labeled "purple". In the preceding, I especially prefer the comma to be after "blue". I could live with the period being inside of "purple.", but still wouldn't favor it (though it does look somewhat comfortingly familiar that way). Also, since this is technical writing, sometimes the things in quotes have to be taken literally, and a comma inside the quote could confuse things.

As far as the other changes, I have already expressed my opinions on most of them -- some of them are good, some are marginally better, some, in my opinion, slightly less good, some I didn't like, and the ones I didn't comment on I thought were at least OK. So I don't know how you should proceed with the PR.

I think I may have known about the "+" thing in GitHub at one time, for a little while.

iliakan · 2019-12-01T09:48:10Z

@jchue thank you for your effort! Could you please update the Pull Request according to the discussion?

paroche · 2019-12-02T04:24:32Z

You mean start a discussion on each of the, what, 70?, lines being edited? Or is there a way to change them directly (without creating a new PR)? The former would be incredibly tedious. The latter might be workable.

iliakan · 2019-12-02T06:46:11Z

The author may correct the PR by pushing more commits. Or we can just manually import some worthy changes from this PR and close it.

iliakan · 2019-12-02T06:55:10Z

@paroche maybe you could review that and just push to master the good changes?

I can do that myself, but I'm unable to validate all the changes. They are not about the content, but about the grammar. So if you approve everything (Except the quotes and the spaces around dash), let me know, then I'll do that.

jchue · 2019-12-02T06:59:52Z

Gents, I have no issue making the changes. Just let me know what you prefer. Would it help if I updated the quotes and dashes first and/or broke up the PR into smaller portions to help with your review?

iliakan · 2019-12-02T07:01:20Z

@paroche, please respond as you're the grammar guy in the room =)

paroche · 2019-12-02T07:15:17Z

If jchue would revise his changes w/ respect to the spaces before dashes and leaving the punctuation out of the quotation marks, and perhaps consider my other opinions from my long comment above, then break it into more bite-sized pieces, that would be cool. Not sure which comment you were asking me to respond to.

Rephrasing what does delegation do for us question.

'alternative of' -> 'alternative to'

'add same handling' -> 'add the same handling' 'and alike' -> 'and the like' 'if' -> 'whether'

in the control control forms section, fixed mistake selectionEnd and selectionStart were both said to be start position

Removed duplicated `also`.

added a missing word

'and want' to implement...

'that allow to' -> 'that allow us to'

'allows to' -> 'allows us to'

'use the event delegation' -> 'use event delegation'

Adding 'object' after 'Property descriptor' -- even though it is said not far above that the 'property descriptor' returned by `Object.getOwnPropertyDescriptor` is an object, I think it wouldn't hurt to discretely include that info here (though of course it's also implied by the usage in the examples). Especially if someone is quickly scanning the article looking for `Object.defineProperty` and didn't just read the part above.

paroche · 2019-12-07T22:11:32Z

1-js/02-first-steps/05-types/article.md

+const bigInt = 1234567890123456789012345678901234567890n;
+```
+
+As `BigInt` numbers are rarely needed, we devoted them a separate chapter <info:bigint>.


Suggest "we devoted a separate chapter to them...". (as is is ungrammatical).

paroche · 2019-12-07T22:17:27Z

1-js/05-data-types/02-number/article.md

 Now let's write something very small. Say, 1 microsecond (one millionth of a second):

 ```js
 let ms = 0.000001;
 ```

-Just like before, using `"e"` can help. If we'd like to avoid writing the zeroes explicitly, we could say:
+Just like before, using `"e"` can help. If we'd like to avoid writing the zeroes explicitly, we could say the same as:


Recommend "say the same thing as:". Or, maybe better, just "say instead:"

paroche · 2019-12-07T22:23:20Z

1-js/05-data-types/02-number/article.md

@@ -271,13 +274,11 @@ JavaScript doesn't trigger an error in such events. It does its best to fit the
 ```smart header="Two zeroes"
 Another funny consequence of the internal representation of numbers is the existence of two zeroes: `0` and `-0`.

-That's because a sign is represented by a single bit, so every number can be positive or negative, including a zero.
+That's because a sign is represented by a single bit, so it can be set or not set for any number including a zero.


I prefer the original. Or, to get more wordy: "...a single bit which can be set for any number, so every number can be positive or negative, including zero". But I find it pretty clear the way it is (or was).

To me "set" does not necessarily mean "set to '1'" -- it could also be set to '0'. So I don't see "set or not set" as being necessary.

paroche · 2019-12-07T22:27:11Z

1-js/05-data-types/02-number/article.md


- Append `"e"` with the zeroes count to the number. Like: `123e6` is `123` with 6 zeroes.
- A negative number after `"e"` causes the number to be divided by 1 with given zeroes. That's for one-millionth or such.
+- Append `"e"` with the zeroes count to the number. Like: `123e6` is the same as `123` with 6 zeroes `123000000`.


I thought it was OK the way it was, but if you're going to do it this way, it would be better with a colon after "zeroes":

"the same as 123 with 6 zeroes: 12300000.

paroche · 2019-12-07T22:28:27Z

1-js/05-data-types/02-number/article.md

- Append `"e"` with the zeroes count to the number. Like: `123e6` is `123` with 6 zeroes.
- A negative number after `"e"` causes the number to be divided by 1 with given zeroes. That's for one-millionth or such.
+- Append `"e"` with the zeroes count to the number. Like: `123e6` is the same as `123` with 6 zeroes `123000000`.
+- A negative number after `"e"` causes the number to be divided by 1 with given zeroes. E.g. `123e-6` means `0.000123` (`123` millionth).


(123 millionths)

paroche · 2019-12-07T22:34:28Z

1-js/07-object-properties/02-property-accessors/article.md

-```smart header="No way to handle `delete`"
-There's no similar method to handle deletion of an accessor property. Only getter/setter methods may exist.
-```
+As the result, we have a "virtual" property `fullName`. It is readable and writable.


I kind of liked the "in fact does not exist" part. Though that is already implied by "virtual", a bit of emphasis can be helpful. (Though I would have been tempted to rephrase it as "but does not in fact exist"). Without it, "It is readable and writable" seems to just kind of hang there.

paroche · 2019-12-07T22:41:31Z

2-ui/1-document/07-modifying-document/12-sort-table/solution.md

-let sortedRows = Array.from(table.rows)
-  .slice(1)
-  .sort((rowA, rowB) => rowA.cells[0].innerHTML > rowB.cells[0].innerHTML ? 1 : -1);
+let sortedRows = Array.from(table.tBodies[0].rows) // (1)


I like it. 😎

paroche · 2019-12-07T22:52:45Z

2-ui/1-document/11-coordinates/article.md


-Here we mention negative `width/height` only for you to understand why these seemingly duplicate properties are not actually duplicates.
+In practice though, `elem.getBoundingClientRect()` always returns positive width/height, here we mention negative `width/height` only for you to understand why these seemingly duplicate properties are not actually duplicates.


If keeping it all as one sentence, recommend moving the comma: "In practice, though elem.... .

Either that or change later part to "...width/height. Here we ....". And maybe have commas on both sides of 'though':

"In practice, though, elem... always returns positive width/height. Here we mention ..."

That would be my first choice.

paroche · 2019-12-07T22:57:25Z

...ils/3-mousemove-mouseover-mouseout-mouseenter-mouseleave/2-hoverintent/source.view/style.css

@@ -20,9 +24,15 @@
  top: 0;
 }

-.tooltip {
+#tooltip {


I thought the styling had suddenly changed!

paroche · 2019-12-07T23:02:31Z

2-ui/99-ui-misc/01-mutation-observer/article.md


 There are other situations when a third-party script adds something into our document, and we'd like to detect, when it happens, to adapt our page, dynamically resize something etc.

-`MutationObserver` can easily handle this.
+`MutationObserver` allows to implement this.


" allows us to implement this"

paroche · 2019-12-07T23:09:19Z

5-network/02-formdata/article.md

 - `formData.delete(name)` - remove the field with the given `name`,
 - `formData.get(name)` - get the value of the field with the given `name`,
 - `formData.has(name)` - if there exists a field with the given `name`, returns `true`, otherwise `false`

 A form is technically allowed to have many fields with the same `name`, so multiple calls to `append` add more same-named fields.

-There's also method `set`, with the same syntax as `append`. The difference is that `.set` removes all fields with the given `name`, and then appends a new field. So it makes sure there's only field with such `name`, the rest is just like `append`:
+There's also method `set`, with the same syntax as `append`. The difference is that `.set` removes all fields with the given `name`, and then appends a new field. So it makes sure there's only one field with such `name`, the rest is just like `append`:


I think

'only one field with such a name. The rest is ..."

or 'only one field with such a name; the rest is..."

or 'only one field with such a name, then the rest is..."

would be better. Probably prefer the last option.

Make minor grammar corrections/updates

ffbb05e

iliakan requested a review from paroche November 30, 2019 07:01

iliakan added the waiting for feedback label Dec 1, 2019

paroche and others added 15 commits December 7, 2019 13:47

Update article.md

73a8841

Rephrasing what does delegation do for us question.

Update article.md

de1b2e1

'alternative of' -> 'alternative to'

Update article.md

1415467

'add same handling' -> 'add the same handling' 'and alike' -> 'and the like' 'if' -> 'whether'

Fix: typos

88abe30

Fix err in syntax

bbc374c

Update article.md

6285691

in the control control forms section, fixed mistake selectionEnd and selectionStart were both said to be start position

fixed a word 'operational' to be 'operating'

49b8c6a

minor

4064535

Update article.md

ddf91b4

Removed duplicated `also`.

minor

dafd592

modified a sentence

a6629b4

added a missing word

Update article.md

a478839

'and want' to implement...

Update article.md

bfa6eb8

'that allow to' -> 'that allow us to'

Update article.md

05cc2be

'allows to' -> 'allows us to'

Update task.md

71d7eb8

'use the event delegation' -> 'use event delegation'

paroche and others added 9 commits December 7, 2019 13:48

Update article.md

5fdbe40

Update article.md

ba44712

content fixes, javascript-tutorial#1646

23f259c

fixes javascript-tutorial#1599

7450dbe

fixes javascript-tutorial#1591

c4b6d5d

closes javascript-tutorial#1591

c300610

fixes javascript-tutorial#1653

3f840b7

Make minor grammar corrections/updates to async/callbacks

4a2d496

jchue closed this Dec 7, 2019

jchue deleted the patch-1 branch December 7, 2019 21:55

jchue mentioned this pull request Dec 7, 2019

Make minor grammar corrections/updates to async/callbacks #1659

Closed

paroche reviewed Dec 7, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make minor grammar corrections/updates #1612

Make minor grammar corrections/updates #1612

jchue commented Nov 18, 2019

CLAassistant commented Nov 18, 2019 •

edited

Loading

iliakan commented Nov 30, 2019

paroche commented Nov 30, 2019 •

edited

Loading

iliakan commented Nov 30, 2019

paroche commented Nov 30, 2019

iliakan commented Dec 1, 2019

paroche commented Dec 2, 2019

iliakan commented Dec 2, 2019

iliakan commented Dec 2, 2019 •

edited

Loading

jchue commented Dec 2, 2019

iliakan commented Dec 2, 2019

paroche commented Dec 2, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019

paroche Dec 7, 2019


		Here we mention negative `width/height` only for you to understand why these seemingly duplicate properties are not actually duplicates.
		In practice though, `elem.getBoundingClientRect()` always returns positive width/height, here we mention negative `width/height` only for you to understand why these seemingly duplicate properties are not actually duplicates.

Make minor grammar corrections/updates #1612

Make minor grammar corrections/updates #1612

Conversation

jchue commented Nov 18, 2019

CLAassistant commented Nov 18, 2019 • edited Loading

iliakan commented Nov 30, 2019

paroche commented Nov 30, 2019 • edited Loading

iliakan commented Nov 30, 2019

paroche commented Nov 30, 2019

iliakan commented Dec 1, 2019

paroche commented Dec 2, 2019

iliakan commented Dec 2, 2019

iliakan commented Dec 2, 2019 • edited Loading

jchue commented Dec 2, 2019

iliakan commented Dec 2, 2019

paroche commented Dec 2, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CLAassistant commented Nov 18, 2019 •

edited

Loading

paroche commented Nov 30, 2019 •

edited

Loading

iliakan commented Dec 2, 2019 •

edited

Loading