updated README_1 and MATH

Author: lucasnyc

docs/md/README_1.md

@@ -3,7 +3,7 @@ of the textbook
 <a href="https://sourceacademy.org/sicpjs">Structure and Interpretation
 of Computer Programs, JavaScript Adaptation</a> (SICP JS).
 
-## What names are predeclared in Source §1?
+## What names are predeclared in Python §1?
 
 On the right, you see all predeclared names of Python §1, in alphabetical
 order. Click on a name to see how it is defined and used.
@@ -48,17 +48,18 @@ Within expressions, you can let a <EM>predicate</EM> determine whether
 a <EM>consequent expression</EM>
 gets evaluated or an <EM>alternative expression</EM>. This is done by writing,
 for example
-<PRE><CODE>return p(x) ? 7 : f(y);</CODE></PRE>
+<PRE><CODE>return 7 if p() else f(y)</CODE></PRE>
 Read more on conditional expressions in
 <a href="https://sourceacademy.org/sicpjs/1.1.6">section 1.1.6
 Conditional Expressions and Predicates</a>.
 <EM>Conditional evaluation</EM> is also possible within statements, for
 example the body of a function declaration. For that, you can use <EM>conditional
-statements</EM>, for example:<PRE><CODE>if (p(x)) {
-    return 7;
-} else {
-    return f(y);
-}</CODE></PRE>
+statements</EM>, for example:
+<PRE><CODE>if p(x):
+    return 7
+else:
+    return f(y)
+</CODE></PRE>
 Read about <EM>conditional statements</EM> in
 <a href="https://sourceacademy.org/sicpjs/1.3.2">section 1.3.2
 Function Definition Expressions</a>.
@@ -67,56 +68,57 @@ Function Definition Expressions</a>.
 
 A function declaration is a statement that declares a name and binds it
 to a function. For example
-<PRE><CODE>function square(x) {
-    return x * x;
-}</CODE>
+<PRE><CODE>def square(x):
+    return x * x
+</CODE>
 </PRE>
 declares the name `square` and binds it to a squaring function, so that it can be applied
-as in `square(5);`. You can read about function declaration statements in textbook
+as in `square(5)`. You can read about function declaration statements in textbook
 <a href="https://sourceacademy.org/sicpjs/1.1.4">section 1.1.4 Functions</a>.
 
 Sometimes, it's not necessary to give a name to a function: You may
 want to create a function only to pass it to some other function as argument.
-For that, Source
+For that, Python §
 supports function definition expressions. For example
-<PRE><CODE>(x => x * x)(3); // returns 9</CODE>
+<PRE><CODE>(lambda x: x * x)(3) // returns 9</CODE>
 </PRE>
 creates a square function just like the function declaration above,
 but does not give it a name.
 Its only purpose it to be applied to the number 3. See also
 textbook
 <a href="https://sourceacademy.org/sicpjs/1.3.2">section 1.3.2 Function Definition Expressions</a>.
 
-### Blocks
-
-Blocks make up the bodies of functions and the consequent and alternative statements of
-conditional statements. You can use blocks also elsewhere in your program, if you
-want to declare constants local to a specific scope. For example in this program
-<PRE><CODE>const a = 1;
-{
-   const a = 2;
-   display(a);
-}
-display(a);</CODE>
+### Scope of declaration
+
+A variable declared outside a function, the variable has a global scope. If you want to 
+declare a variable local to a specific scope, you can declare it in a function.
+For example in this program
+<PRE><CODE>a = 1
+
+def local_scope():
+    a = 2
+    print(a)
+local_scope()
+print(a)</CODE>
 </PRE>
-the first application of `display` shows the value 2, because the
-declaration <B>const</B> `a = 2;` re-declares the constant `a`.
+the first application of `print` shows the value 2, because the
+<B>assignment</B> `a = 2` re-declares the variable `a`.
 However, the second application
-of `display` shows the value 1, because
-the declaration <B>const</B> `a = 2;` is limited in scope by its surrounding block.
-You can read more about <EM>blocks</EM> in
+of `print` shows the value 1, because
+the <B>assignment</B> `a = 2` is limited in local scope by defining it in the function.
+You can read more about <EM>scope</EM> in
 <a href="https://sourceacademy.org/sicpjs/1.1.8">section 1.1.8
 Functions as Black-Box Abstractions</a>.
 
 ### Boolean operators
 
-Boolean operators in Source have a special meaning. Usually, an operator combination
+Boolean operators in Python § have a special meaning. Usually, an operator combination
 evaluates all its arguments and then applies the operation to which the operator refers.
-For example, `(2 * 3) + (4 * 5)` evaluates `2 * 3` and `4 * 5` first, before the addition
-is carried out. However, the operator `&&` works differently. An expression
-`e1 && e2` should be seen as an abbreviation for `e1 ? e2 : false`. The expression
-`e2` only gets evaluated if `e1` evaluates to `true`. The behaviour of `||` is similar:
-`e1 || e2` should be seen as an abbreviation for `e1 ? true : e2`. More on these
+For example, `(2 * 3) + (4 * 5)` evaluates to `2 * 3` and `4 * 5` first, before the addition
+is carried out. However, the operator <B>and</B> works differently. An expression
+`e1 and e2` should be seen as an abbreviation for `e2 if e1 else False`. The expression
+`e2` only gets evaluated if `e1` evaluates to `True`. The behaviour of <B>or</B> operator is similar:
+`e1 or e2` should be seen as an abbreviation for `True if e1 else e2`. More on these
 two boolean operators in textbook
 <a href="https://sourceacademy.org/sicpjs/1.1.6">section 1.1.6 Conditional
 Expressions and Predicates</a>.
@@ -125,12 +127,12 @@ Expressions and Predicates</a>.
 
 A program or the body of a block does not need to consist of a single statement.
 You can write multiple statements in a row. In the REPL ("Read-Eval-Print-Loop")
-of a Source implementation, you can write
-<PRE><CODE>cube(7);
-square(5);</CODE></PRE>
+of a Python § implementation, you can write
+<PRE><CODE>cube(7)
+square(5)</CODE></PRE>
 The statements in such a sequence are evaluated in the given order. The
 result of evaluating the sequence is the result of evaluating the last
-statement in the sequence, in this case `square(5);`.
+statement in the sequence, in this case `square(5)`.
 Read more about sequences in
 <a href="https://sourceacademy.org/sicpjs/1.1.2">section 1.1.2
 Naming and the Environment</a> of the textbook.
@@ -139,6 +141,6 @@ Naming and the Environment</a> of the textbook.
 
 For our development team, we are maintaining a definitive description
 of the language, called the
-<a href="../source_1.pdf">Specification of Source §1</a>. Feel free to
+<a href="../python_1.pdf">Specification of Python §1</a>. Feel free to
 take a peek.
 

docs/md/README_MATH.md

@@ -1,22 +1,15 @@
-All names in the JavaScript `Math` library are predeclared in Source. The
+All names in the Python `Math` module are predeclared in Python §. The
 complete specifications are given in 
-<a href="https://www.ecma-international.org/ecma-262/9.0/index.html#sec-math-object">ECMAScript
-Specification, Section 20.2</a>, and a summary is available here, by clicking
+<a href="https://docs.python.org/3/library/math.html">Python
+Standard Library Math Documentation</a>, and a summary is available here, by clicking
 on the names on the right.
-<B>As learner of Source, you are not expected to learn all of these, right away. But
+<B>As learner of Python §, you are not expected to learn all of these, right away. But
 you might want to remember where you can look for them: Here!</B>
 Click on a name to see how it is defined and used.
 <P/>
 Note that we expect
 all arguments of `math_...`
-functions to be numbers, as defined by the function `is_number`. An implementation
-of Source does not need to check whether all arguments of `math_...`
-functions are indeed numbers.
+functions to be either an integer or float, as defined by the function `is_int` and `is_float`. An implementation
+of Python § does not need to check whether all arguments of `math_...`
+functions are indeed integer or float.
 <P/>
-Two of the specifications make use of the function ToUint32, which is defined as follows:
-ToUint32 converts argument to one of 2<SUP>32</SUP> integer values in the
-range 0 through 2<SUP>32</SUP>-1, inclusive. This operation functions as follows:
-
-If the argument x is NaN, +0, -0, +∞, or -∞, ToUint32(x) return +0.
-Otherwise, let `int` be the mathematical value that is the same sign as number and
-whose magnitude is `math_floor(math_abs(x))`. ToUint32(x) returns `int` modulo 2<SUP>32</SUP>.