Update first five chapters for mkdocs

thejsway · Dec 5, 2022 · cdc4352 · cdc4352
1 parent c085a4d
commit cdc4352
Show file tree

Hide file tree

Showing 5 changed files with 222 additions and 182 deletions.
diff --git a/manuscript/chapter01.md b/manuscript/chapter01.md
@@ -1,23 +1,7 @@
-# 3, 2, 1... Code!
+# 3, 2, 1... Code
 
 Let's get started! This chapter will introduce you to the fundamentals of programming including values, types, and program structure.
 
-## TL;DR
-
-* The JavaScript command `console.log()` shows a message in the **console**, an information zone available in most JavaScript environments.
-
-* A **value** is a piece of information. The **type** of a value defines its role and the operations applicable to it.
-
-* The JavaScript language uses the **number** type to represent a numerical value (with or without decimals) and the **string** type to represent text.
-
-* A string value is surrounded by a pair of single quotes (`'...'`) or a pair of quotation marks (`"..."`).
-
-* Arithmetic operations between numbers are provided by the `+`, `-`, `*` and `/` operators. Applied to two strings, the `+` operator joins them together. This operation is called **concatenation**.
-
-* A computer program is made of several **lines of code** read sequentially during execution.
-
-* **Comments** (`// ...` or `/* ... */`) are non-executed parts of code. They form a useful program documentation.
-
 ## Your first program
 
 Here's our very first JavaScript program.
@@ -57,7 +41,9 @@ A **string** in JavaScript is text surrounded by quotation marks, such as `"This
 
 You can also define strings with a pair of single quotes: `'This is another string'`. The best practice for single or double quotes is a whole political thing. Use whichever you like, but don't mix the two in the same program!
 
-W> Always remember to close a string with the same type of quotation marks you started it with.
+!!! warning
+
+    Always remember to close a string with the same type of quotation marks you started it with.
 
 To include special characters in a string, use the `\` character (*backslash*) before the character. For example, type `\n` to add a new line within a string: `"This is\na multiline string"`.
 
@@ -73,7 +59,9 @@ The source code may include empty lines: these will be ignored when the program
 
 Each instruction inside a program is called a **statement**. A statement in JavaScript usually ends with a **semicolon** (albeit it's not strictly mandatory). Your program will be made up of a series of these statements.
 
-I> You usually write only one statement per line.
+!!! tip
+
+    You usually write only one statement per line.
 
 ### Execution flow
 
@@ -95,7 +83,9 @@ Depending on your work environment, the execution result may not include quotes
 
 ![Execution result in browser console](images/chapter01-04.png)
 
-I> As expected, a division by zero (`12/0`) results in an `Infinity` value.
+!!! note
+
+    As expected, a division by zero (`12/0`) results in an `Infinity` value.
 
 ### Comments
 
@@ -127,6 +117,22 @@ several lines */
 
 Comments are a great source of info about a program's purpose or structure. Adding comments to complicated or critical parts is a good habit you should build right now!
 
+## TL;DR
+
+* The JavaScript command `console.log()` shows a message in the **console**, an information zone available in most JavaScript environments.
+
+* A **value** is a piece of information. The **type** of a value defines its role and the operations applicable to it.
+
+* The JavaScript language uses the **number** type to represent a numerical value (with or without decimals) and the **string** type to represent text.
+
+* A string value is surrounded by a pair of single quotes (`'...'`) or a pair of quotation marks (`"..."`).
+
+* Arithmetic operations between numbers are provided by the `+`, `-`, `*` and `/` operators. Applied to two strings, the `+` operator joins them together. This operation is called **concatenation**.
+
+* A computer program is made of several **lines of code** read sequentially during execution.
+
+* **Comments** (`// ...` or `/* ... */`) are non-executed parts of code. They form a useful program documentation.
+
 ## Coding time!
 
 Let's put your brand new coding skills into practice.
@@ -135,7 +141,7 @@ Let's put your brand new coding skills into practice.
 
 Write a program that displays your name and age. Here's the result for mine.
 
-![](images/chapter01-03.png)
+![Expected execution result](images/chapter01-03.png)
 
 ### Minimalistic calculator
 

diff --git a/manuscript/chapter02.md b/manuscript/chapter02.md
@@ -2,26 +2,6 @@
 
 You know how to use JavaScript to display values. However, for a program to be truly useful, it must be able to store data, like information entered by a user. Let's check that out.
 
-## TL;DR
-
-* A **variable** is an information storage area. Every variable has a **name**, a **value** and a **type**. In JavaScript, the type of a variable is deduced from the value stored in it: JavaScript is a **dynamically typed** language.
-
-* A variable is declared using the `let` keyword followed by the variable name. To declare a **constant** (a variable whose initial value will never change), it's better to use the `const` keyword instead.
-
-* To give a value to a variable, we use the **assignment operator** `=`. For number variables, the operator `+=` can increase and the operator `++` can **increment** their value.
-
-* The **scope** of a variable is the part of the program where the variable is visible. Variables declared with `let` or `const` are **block-scoped**. A **code block** is a portion of a program delimited by a pair of opening and closing curly braces `{ ... }`.
-
-* An **expression** is a piece of code that combines variables, values and operators. Evaluating an expression produces a value, which has a type.
-
-* Expressions may be included in strings delimited by a pair of backticks (\`). Such a string is called a **template literal**.
-
-* **Type conversions** may happen implicitly during the evaluation of an expression, or explicitly when using the `Number()` and `String()` commands, to obtain respectively a number or a string.
-
-* The `prompt()` and `alert()` commands deal with information input and display under the form of dialog boxes.
-
-* Variable naming is essential to program visibility. Following a naming convention like [camelCase](https://en.wikipedia.org/wiki/Camel_case) is good practice.
-
 ## Variables
 
 ### Role of a variable
@@ -36,7 +16,9 @@ A variable has three main properties:
 * Its **value**, which is the data stored in the variable.
 * Its **type**, which determines the role and actions available to the variable.
 
-I> You don't have to define a variable type explicitly in JavaScript. Its type is deduced from the value stored in the variable and may change while the program runs. That's why we say that JavaScript is a **dynamically typed** language. Other languages, like C or Java, require variable types to always be defined. This is called **static typing**.
+!!! info
+
+    You don't have to define a variable type explicitly in JavaScript. Its type is deduced from the value stored in the variable and may change while the program runs. That's why we say that JavaScript is a **dynamically typed** language. Other languages, like C or Java, require variable types to always be defined. This is called **static typing**.
 
 ### Declaring a variable
 
@@ -51,7 +33,9 @@ console.log(a);
 
 In JavaScript, you declare a variable with the `let`  keyword followed by the variable name. In this example, the variable created is called `a`.
 
-I> Previously, JavaScript variables were declared using the `var` keyword. It's still possible, but in most cases it's simpler to use `let` and `const` instead.
+!!! note
+
+    Previously, JavaScript variables were declared using the `var` keyword. It's still possible, but in most cases it's simpler to use `let` and `const` instead.
 
 Here's the execution result for this program.
 
@@ -75,7 +59,9 @@ console.log(a);
 
 We modified the variable by assigning it a value. `a = 3.14` reads as "a receives the value 3.14".
 
-E> Be careful not to confuse the assignment operator `=` with mathematical equality! You'll soon see how to express equality in JavaScript.
+!!! warning
+
+    Be careful not to confuse the assignment operator `=` with mathematical equality! You'll soon see how to express equality in JavaScript.
 
 You can also combine declaring a variable and assigning it a value in one line. Just know that, within this line, you're doing two different things at once:
 
@@ -258,6 +244,26 @@ They function in the same way, but the second version is much easier to understa
 
 Naming things is an important part of the programmer's job. Refer to the appendix for some useful advice.
 
+## TL;DR
+
+* A **variable** is an information storage area. Every variable has a **name**, a **value** and a **type**. In JavaScript, the type of a variable is deduced from the value stored in it: JavaScript is a **dynamically typed** language.
+
+* A variable is declared using the `let` keyword followed by the variable name. To declare a **constant** (a variable whose initial value will never change), it's better to use the `const` keyword instead.
+
+* To give a value to a variable, we use the **assignment operator** `=`. For number variables, the operator `+=` can increase and the operator `++` can **increment** their value.
+
+* The **scope** of a variable is the part of the program where the variable is visible. Variables declared with `let` or `const` are **block-scoped**. A **code block** is a portion of a program delimited by a pair of opening and closing curly braces `{ ... }`.
+
+* An **expression** is a piece of code that combines variables, values and operators. Evaluating an expression produces a value, which has a type.
+
+* Expressions may be included in strings delimited by a pair of backticks (\`). Such a string is called a **template literal**.
+
+* **Type conversions** may happen implicitly during the evaluation of an expression, or explicitly when using the `Number()` and `String()` commands, to obtain respectively a number or a string.
+
+* The `prompt()` and `alert()` commands deal with information input and display under the form of dialog boxes.
+
+* Variable naming is essential to program visibility. Following a naming convention like [camelCase](https://en.wikipedia.org/wiki/Camel_case) is good practice.
+
 ## Coding time!
 
 Build a habit of choosing good variable names in all exercises, starting with these ones.
@@ -294,7 +300,9 @@ Write a program that asks the user for a raw price. After that, it calculates th
 
 Write a program that asks for a temperature in Celsius degrees, then displays it in Fahrenheit degrees.
 
-> The conversion between scales is given by the formula: [°F] = [°C] x 9/5 + 32.
+!!! quote
+
+    The conversion between scales is given by the formula: [°F] = [°C] x 9/5 + 32.
 
 ### Variable swapping
 
@@ -312,4 +320,6 @@ console.log(number2); // Should show 5
 
 Add the necessary code to swap the values of variables `number1` and `number2`.
 
-T> This exercise has several valid solutions. You may use more than two variables to solve it.
+!!! tip
+
+    This exercise has several valid solutions. You may use more than two variables to solve it.
diff --git a/manuscript/chapter03.md b/manuscript/chapter03.md
@@ -2,49 +2,6 @@
 
 Up until now, all the code in our programs has been executed chronologically. Let's enrich our code by adding conditional execution!
 
-## TL;DR
-
-* The `if` keyword defines a **conditional statement**, also called a **test**. The associated code block is only run if the **condition** is satisfied (its value is `true`). Thus, a condition is an expression whose evaluation always produces a boolean result (`true` or `false`).
-
-```js
-if (condition) {
-  // Code to run when the condition is true
-}
-```
-
-* The code block associated to an `if` is delimited by a pair of opening and closing braces. To improve visibility, its statements are generally **indented** (shifted to the right).
-
-* The **comparison operators** `===`, `!==`, `<`, `<=`, `>` and `>=` are used to compare numbers inside a condition. All of them return a boolean result.
-
-* An `else` statement can be associated to an `if` to express an **alternative**. Depending on the condition value, either the code block associated to the `if` or the one associated to the `else` will be run, but never both. There is no limit to the depth of condition nesting.
-
-```js
-if (condition) {
-  // Code to run when the condition is true
-}
-else {
-  // Code to run when the condition is false
-}
-```
-
-* Complex conditions can be created using the **logical operators** `&&` ("and"), `||` ("or") and `!` ("not").
-
-* The `switch` statement is used to kick off the execution of one code block among many, depending on the value of an expression.
-
-```js
-switch (expression) {
-case value1:
-  // Code to run when the expression matches value1
-  break;
-case value2:
-  // Code to run when the expression matches value2
-  break;
-...
-default:
-  // Code to run when neither case matches
-}
-```
-
 ## What's a condition?
 
 Suppose we want to write a program that asks the user to enter a number and then displays a message if the number is positive. Here is the corresponding algorithm.
@@ -82,7 +39,9 @@ The pair of opening and closing braces defines the block of code associated with
 
 The condition is always placed in parentheses after the `if`. The statements within the associated code block are shifted to the right. This practice is called **indentation** and helps make your code more readable. As your programs grow in size and complexity, it will become more and more important. The indentation value is often 2 or 4 spaces.
 
-I> When the code block has only one statement, braces may be omitted. As a beginner, you should nonetheless always use braces when writing your first conditions.
+!!! info
+
+    When the code block has only one statement, braces may be omitted. As a beginner, you should nonetheless always use braces when writing your first conditional statements.
 
 ### Conditions
 
@@ -116,7 +75,9 @@ Boolean expressions can be created using the comparison operators shown in the f
 
 In some other programming languages, equality and inequality operators are `==` and `!=`. They also exist in JavaScript, but it's safer to use `===` and `!==` ([more details](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness)).
 
-E> It's easy to confuse comparison operators like `===` (or `==`) with the assignment operator `=`. They're very, very different. Be warned!
+!!! warning
+
+    It's easy to confuse comparison operators like `===` (or `==`) with the assignment operator `=`. They're very, very different. Be warned!
 
 Now let's modify the example code to replace `>` with `>=` and change the message, then test it with the number 0.
 
@@ -183,7 +144,9 @@ if (number > 0) {
 
 Let's wrap our heads around it. If the code block associated to the first `else` is run, then the number has to be either strictly negative or zero. Inside this block, a second `if` statement checks if the number is negative. If it's not, we know for sure that it's zero.
 
-I> When learning to write nested conditions, you should add descriptive comments to each condition, just like in the previous example.
+!!! tip
+
+    When learning to write nested conditions, you should add descriptive comments to each condition, just like in the previous example.
 
 The execution flow for the previous program can be expressed graphically using a **flow diagram**.
 
@@ -210,7 +173,9 @@ if (number > 0) {
 
 Suppose you want to check if a number is between 0 and 100. You're essentially checking if it's "greater than or equal to 0" and "less than or equal to 100". Both sub-conditions must be satisfied at the same time.
 
-I> The expression `0 <= number <= 100` is correct from a mathematical point of view but cannot be written in JavaScript (neither in most other programming languages).
+!!! info
+
+    The expression `0 <= number <= 100` is correct from a mathematical point of view but cannot be written in JavaScript (neither in most other programming languages).
 
 Here's how you'd translate that same check into JS.
 
@@ -220,7 +185,9 @@ if ((number >= 0) && (number <= 100)) {
 }
 ```
 
-I> Parentheses between sub-conditions are not mandatory but I advise you to add them anyway, to avoid nasty bugs in some special cases.
+!!! tip
+
+    Parentheses between sub-conditions are not mandatory but I advise you to add them anyway, to avoid nasty bugs in some special cases.
 
 The `&&` operator ("logical and") can apply to both types of boolean values. `true` will only be the result of the statement if both conditions are true.
 
@@ -389,6 +356,49 @@ switch (x) {
 
 The previous example show `"x = abc"` (the correct result) but also `"x = def"`.
 
+## TL;DR
+
+* The `if` keyword defines a **conditional statement**, also called a **test**. The associated code block is only run if the **condition** is satisfied (its value is `true`). Thus, a condition is an expression whose evaluation always produces a boolean result (`true` or `false`).
+
+```js
+if (condition) {
+  // Code to run when the condition is true
+}
+```
+
+* The code block associated to an `if` is delimited by a pair of opening and closing braces. To improve visibility, its statements are generally **indented** (shifted to the right).
+
+* The **comparison operators** `===`, `!==`, `<`, `<=`, `>` and `>=` are used to compare numbers inside a condition. All of them return a boolean result.
+
+* An `else` statement can be associated to an `if` to express an **alternative**. Depending on the condition value, either the code block associated to the `if` or the one associated to the `else` will be run, but never both. There is no limit to the depth of condition nesting.
+
+```js
+if (condition) {
+  // Code to run when the condition is true
+}
+else {
+  // Code to run when the condition is false
+}
+```
+
+* Complex conditions can be created using the **logical operators** `&&` ("and"), `||` ("or") and `!` ("not").
+
+* The `switch` statement is used to kick off the execution of one code block among many, depending on the value of an expression.
+
+```js
+switch (expression) {
+case value1:
+  // Code to run when the expression matches value1
+  break;
+case value2:
+  // Code to run when the expression matches value2
+  break;
+...
+default:
+  // Code to run when neither case matches
+}
+```
+
 ## Coding time!
 
 Here are a few pieces of advice about these exercises:
@@ -448,8 +458,8 @@ Write a program that accepts a month number (between 1 and 12), then shows the n
 
 Write a program that asks for a time under the form of three information (hours, minutes, seconds). The program calculates and shows the time one second after. Incorrect inputs must be taken into account.
 
-> This is not as simple as it seems... Look at the following results to see for yourself:
->
-> * 14h17m59s => 14h18m0s
-> * 6h59m59s => 7h0m0s
-> * 23h59m59s => 0h0m0s (midnight)
+This is not as simple as it seems... Look at the following results to see for yourself:
+
+* 14h17m59s should give 14h18m0s
+* 6h59m59s should give 7h0m0s
+* 23h59m59s should give 0h0m0s (midnight)