Merge branch 'slides/add_notes_tips_warnings_up_to_basic' into 'master'

Add warnings, tips, notes

See merge request feng/training/material!298

Author: leogermond

courses/fundamentals_of_ada/020_declarations/01-introduction.rst

@@ -36,13 +36,14 @@ Declarations
     - et cetera
 
 * In a :dfn:`declarative part`
+
 * Example: :ada:`N : Type := Value;`
 
     - ``N`` is usually an :dfn:`identifier`
 
-* Declaration **must precede** use
 * **Some** implicit declarations
 
     - **Standard** types and operations
     - **Implementation**-defined
 
+.. warning:: Declaration **must precede** use

courses/fundamentals_of_ada/020_declarations/02-identifiers_and_comments.rst

@@ -31,14 +31,14 @@ Identifiers
          A_
          _space_person
 
+.. warning:: Reserved words are **forbidden**
+
 * Character set **Unicode** 4.0
 * Case **not significant**
 
    - `SpacePerson` |equivalent| `SPACEPERSON`
    - ...but **different** from `Space_Person`
 
-* Reserved words are **forbidden**
-
 ----------------
 Reserved Words
 ----------------

courses/fundamentals_of_ada/020_declarations/03-literals.rst

@@ -34,7 +34,8 @@ Decimal Numeric Literals
         numeral [.numeral] E [+numeral|-numeral]
       numeral ::= digit {['_'] digit}
 
-* Underscore is not significant
+.. tip:: Underscore is **not** significant and helpful for grouping
+
 * **E** (exponent) must always be integer
 * Examples
 

courses/fundamentals_of_ada/020_declarations/05-universal_types.rst

@@ -34,12 +34,12 @@ Numeric Literals Are Universally Typed
 
 * Compiler handles typing
 
-   - No bugs with precision
+.. note:: No bugs with precision
 
-  .. code:: Ada
+.. code:: Ada
 
-     X : Unsigned_Long := 0;
-     Y : Unsigned_Short := 0;
+   X : Unsigned_Long := 0;
+   Y : Unsigned_Short := 0;
 
 ----------------------------------------
 Literals Must Match "Class" of Context

courses/fundamentals_of_ada/020_declarations/06-named_numbers.rst

@@ -51,12 +51,13 @@ Named Number Benefit
 * Evaluation at **compile time**
 
     - As if **used directly** in the code
-    - **Perfect** accuracy
 
-  .. code:: Ada
+.. tip:: Useful due to their **perfect** accuracy
 
-    Named_Number   : constant :=       1.0 / 3.0;
-    Typed_Constant : constant Float := 1.0 / 3.0;
+.. code:: Ada
+
+   Named_Number   : constant :=       1.0 / 3.0;
+   Typed_Constant : constant Float := 1.0 / 3.0;
 
 .. container:: latex_environment footnotesize
 

courses/fundamentals_of_ada/020_declarations/07-scope_and_visibility.rst

@@ -61,9 +61,8 @@ Scope and "Lifetime"
 ----------------------
 
 * Object in scope |rightarrow| exists
-* No *scoping* keywords
 
-    - C's :c:`static`, :c:`auto` etc...
+.. note:: No *scoping* keywords (C's :c:`static`, :c:`auto` etc...)
 
 .. image:: block_scope_example.jpeg
     :height: 50%
@@ -101,9 +100,11 @@ Overcoming Hiding
 
    - Needs named scope
 
-* Homographs are a *code smell*
+.. warning::
 
-    - May need **refactoring**...
+    * Homographs are a *code smell*
+
+        - May need **refactoring**...
 
 .. code:: Ada
 

courses/fundamentals_of_ada/030_basic_types/01-introduction.rst

@@ -15,7 +15,8 @@ Strong Typing
 
    - **Check** of values and operations
    - Easy for a computer
-   - Developer can focus on **earlier** phase: requirement
+
+.. tip:: Developer can focus on **earlier** phase: requirement
 
 ----------------------------------------
 Strongly-Typed Vs Weakly-Typed Languages
@@ -198,7 +199,8 @@ Type Model Run-Time Costs
 * **Same performance** for identical programs
 
    - Run-time type checks can be disabled
-   - Compile-time check is *free*
+
+.. note:: Compile-time check is *free*
 
 .. container:: columns
 

courses/fundamentals_of_ada/030_basic_types/02-discrete_numeric_types.rst

@@ -51,9 +51,11 @@ Predefined Signed Integer Types
    - Guaranteed ranges: :ada:`Short_Integer` ``<=`` :ada:`Integer` ``<=`` :ada:`Long_Integer`
    - Ranges are all **implementation-defined**
 
-* Portability not guaranteed
+.. warning::
 
-   - But may be difficult to avoid
+    Portability not guaranteed
+        
+        * But usage may be difficult to avoid
 
 ---------------------------------
 Operators for Signed Integer Type
@@ -67,12 +69,13 @@ Operators for Signed Integer Type
    :multiplying operator: :ada:`* | / | mod | rem`
    :highest precedence operator: :ada:`** | abs`
 
-* *Note*: for exponentiation :ada:`**`
+.. note::
 
-   - Result will be a signed integer
-   - So power **must** be :ada:`Integer` ``>= 0``
+    Exponentiation (:ada:`**`) result will be a signed integer
 
-* Division by zero |rightarrow| :ada:`Constraint_Error`
+       - So power **must** be :ada:`Integer` ``>= 0``
+
+.. warning:: Division by zero |rightarrow| :ada:`Constraint_Error`
 
 ------------------------
 Signed Integer Overflows

courses/fundamentals_of_ada/030_basic_types/02-discrete_numeric_types_with_mod.rst

@@ -51,9 +51,11 @@ Predefined Signed Integer Types
    - Guaranteed ranges: :ada:`Short_Integer` ``<=`` :ada:`Integer` ``<=`` :ada:`Long_Integer`
    - Ranges are all **implementation-defined**
 
-* Portability not guaranteed
+.. warning::
 
-   - But may be difficult to avoid
+    Portability not guaranteed
+
+       - But usage may be difficult to avoid
 
 ---------------------------------
 Operators for Signed Integer Type
@@ -67,12 +69,13 @@ Operators for Signed Integer Type
    :multiplying operator: :ada:`* | / | mod | rem`
    :highest precedence operator: :ada:`** | abs`
 
-* *Note*: for exponentiation :ada:`**`
+.. note::
+
+    Exponentiation (:ada:`**`) result will be a signed integer
 
-   - Result will be a signed integer
-   - So power **must** be :ada:`Integer` ``>= 0``
+       - So power **must** be :ada:`Integer` ``>= 0``
 
-* Division by zero |rightarrow| :ada:`Constraint_Error`
+.. warning:: Division by zero |rightarrow| :ada:`Constraint_Error`
 
 ------------------------
 Signed Integer Overflows
@@ -119,7 +122,7 @@ Modular Types
 * **Unsigned** values
 * Adds operations and attributes
 
-    * Typically **bit-wise** manipulation
+.. note:: Typically **bit-wise** manipulation
 
 * Syntax
 

courses/fundamentals_of_ada/030_basic_types/07-real_types.rst

@@ -77,10 +77,12 @@ Predefined Floating Point Types
    - :ada:`Long_Float` ``>= 11`` digits
 
 * General-purpose
-* Best to **avoid** predefined types
 
-   - Loss of **portability**
-   - Easy to avoid
+.. tip::
+
+    It is best, and easy, to **avoid** predefined types
+
+       - To keep **portability**
 
 -------------------------------
 Floating Point Type Operators
@@ -94,9 +96,11 @@ Floating Point Type Operators
    :multiplying operator: :ada:`* | /`
    :highest precedence operator: :ada:`** | abs`
 
-* *Note* on floating-point exponentiation ``**``
+.. note::
 
-   - Power must be :ada:`Integer`
+   Exponentiation (:ada:`**`) result will be real
+
+   - So power must be :ada:`Integer`
 
       + Not possible to ask for root
       + :ada:`X**0.5` |rightarrow| :ada:`sqrt (x)`
@@ -140,7 +144,8 @@ Numeric Types Conversion
 * Special rule: can always convert between numeric types
 
     - Explicitly
-    - :ada:`Float` |rightarrow| :ada:`Integer` causes **rounding**
+
+.. warning:: :ada:`Float` |rightarrow| :ada:`Integer` causes **rounding**
 
 .. code:: Ada