Comments from reading §1

[TobiasWrigstad]

"our procedural thoughts" is translated to "our process descriptions"

I am not sure it is correct to describe JavaScript as (originally) a language for "controlling browsers". More for creating dynamic content, or "scripting the web". Controlling the browsers seems much higher up the food chain.

"JavaScript is also used for scripting dashboard widgets in Apple computers running the OS X operating system" <--- this is a bit dated these days. And in 2020, OS X will be rechristened as macOS. I propose dropping this bit.

The footnote in
file:///chapters/1.1.html#footnote-link-1
has missing translations without a comment.

I am not super keen on the term "expression statement". Quite a mouthful. Maybe after introduction we can abuse notation and simply say expression?

A small aside is that the differences between the original and the JavaScript versions are often unnecessarily large, at least as portrayed in the split SICP version. Rather than highlighting one or two words that differ, entire sentences are portrayed as updated.

"Of course, the JavaScript interpreter needs to execute the constant declaration for size before the name size can be used in an expression." <--- I propose to strike the "of course" which serves no purpose

Online SICP though: why do we divide the text into subpages? It does not make "web sense" to me, and it removes the ability to search on a page etc. One page per subsection is perhaps better?

In paragraph
file:///chapters/1.1.4.html#p3
there is a change from "multiply it by itself" to "take it times itself". I don't see the point of this change. (Echoed in comment in following code example, and print-only part.)

The code example here
file:///chapters/1.1.5.html#p2
does not end in a ";". While this makes aesthetic sense, it means that the code it leads to does not compile. Is there a way to add the ";" in without having it appear in the textbook?

Paragraph file:///chapters/1.1.6.html#p9 does not explain what the primitive predicates are which is not obvious. Further down, we do not give the english names of &&, || and !, which wasn't needed in the original version because the operators were keywords.

[TobiasWrigstad]

@martin-henz Does the above work as a format for feedbacking, or do you prefer something else?

[martin-henz]

@martin-henz Does the above work as a format for feedbacking, or do you prefer something else?

The format is good. I'll reply inline here, and make a PR that refers to this issue.

[martin-henz]

"our procedural thoughts" is translated to "our process descriptions"

Yes, I was looking for "procedural" vs "functional" and didn't want "procedural" to be so prominent, because we are using "functional" in many places. But with this one, I think I've overdone it. So I'm reverting back to the original in #271.

I am not sure it is correct to describe JavaScript as (originally) a language for "controlling browsers". More for creating dynamic content, or "scripting the web". Controlling the browsers seems much higher up the food chain.

The motivation for JavaScript was very narrow in the beginning, see https://en.wikipedia.org/wiki/Brendan_Eich#Netscape_and_JavaScript

The company Netscape hired Eich for the specific purpose to make a language that can control the Netscape browser from within web pages.

"JavaScript is also used for scripting dashboard widgets in Apple computers running the OS X operating system" <--- this is a bit dated these days. And in 2020, OS X will be rechristened as macOS. I propose dropping this bit.

I wanted to parallel the Scheme original here, and say something about how JavaScript is used. I'm changing the sentence to "The majority of JavaScript programs (as of 2020) are embedded in web pages and interpreted by browsers, but JavaScript is increasingly used as a general-purpose programming language, using systems such as Node.js." in #271.

The footnote in
file:///chapters/1.1.html#footnote-link-1
has missing translations without a comment.

Nice catch. I mistakenly concluded that these lines are not relevant to the adaptation, but the footnote is general enough to remain unchanged: It talks about "Some computer systems" so no problem.

BTW, I'm using http for testing the pages locally: http://localhost:8080/. I've made a yarn command for this, yarn try, to fire up a web server on localhost.

I am not super keen on the term "expression statement". Quite a mouthful. Maybe after introduction we can abuse notation and simply say expression?

I think we should stick to "expression statement". This is a deeply established JavaScript feature. Best be explicit about it and use it consistently throughout the book. This is well established in other JavaScript textbooks and the ECMAScript specs.

A small aside is that the differences between the original and the JavaScript versions are often unnecessarily large, at least as portrayed in the split SICP version. Rather than highlighting one or two words that differ, entire sentences are portrayed as updated.

Yes, will try to fix these, if I have time.

"Of course, the JavaScript interpreter needs to execute the constant declaration for size before the name size can be used in an expression." <--- I propose to strike the "of course" which serves no purpose

OK fixed in #271.

Online SICP though: why do we divide the text into subpages? It does not make "web sense" to me, and it removes the ability to search on a page etc. One page per subsection is perhaps better?

I don't quite understand this comment. At the moment, we have one page per subsection. Do you propose one page per section?

In paragraph
file:///chapters/1.1.4.html#p3
there is a change from "multiply it by itself" to "take it times itself". I don't see the point of this change. (Echoed in comment in following code example, and print-only part.)

The point of the change is to better reflect infix notation, and to provide an intuition for "return". Here is the current PDF to see the issue.

For comparison, here is the original (the actual book has arrows; this is from the online PDF, where the arrows are lines.)

In #271, I'm adding a COMMENT to explain this.

The code example here
file:///chapters/1.1.5.html#p2
does not end in a ";". While this makes aesthetic sense, it means that the code it leads to does not compile. Is there a way to add the ";" in without having it appear in the textbook?

Yes and yes: It makes aesthetic sense and is consistent with the "evaluation of the application expression". And yes, I've added a <JAVASCRIPT_RUN> tag for this exact reason. (There is also a <JAVASCRIPT_TEST> tag that specifies an alternative program just for the purpose of generating test cases via yarn js.)

Fixed in #271 by inserting a JAVASCRIPT_RUN tag.

Paragraph file:///chapters/1.1.6.html#p9 does not explain what the primitive predicates are which is not obvious. Further down, we do not give the english names of &&, || and !, which wasn't needed in the original version because the operators were keywords.

Fixed in #271. I added explanatory sentences introducing the words "logical conjunction", "logical disjunction" and "logical negation", and added footnotes what these terms mean in English. (By the way, the original contains these words but doesn't explain them, which is not so good.)

[TobiasWrigstad]

Hmm. I don't see anything resembling

The company Netscape hired Eich for the specific purpose to make a language that can control the Netscape browser from within web pages

in the link you posted above.

[TobiasWrigstad]

I wanted to parallel the Scheme original here

Perfect! I am all for it, I just felt like the content of the parallel structure was dated. New suggestion is perfect.

[TobiasWrigstad]

I think we should stick to "expression statement".

You are right. I am convinced.

[TobiasWrigstad]

I don't quite understand this comment. At the moment, we have one page per subsection. Do you propose one page per section?

Yes. I think one page per chapter is too coarse grained, but the current setup is too fine grained. I think it is quite common to navigate in a page by searching, and this is impeded by the tendency to make pages (IMO too) short.

[TobiasWrigstad]

The point of the change is to better reflect infix notation

Yes ofc. I see it now. Great.

[martin-henz]

Hmm. I don't see anything resembling

The company Netscape hired Eich for the specific purpose to make a language that can control the Netscape browser from within web pages

in the link you posted above.

Well, 'Eich originally joined intending to put Scheme "in the browser"'. His job scope was quite narrow. I think we can say JavaScript was conceived as a language for controlling the browser.

I'm keen on this because it matches the Lisp story: From a very specific purpose (in the case of Lisp "a formalism for reasoning about the use of certain kinds of logical expressions, called recursion equations".

So in both cases we have a trajectory from specific to general-purpose.