Update per review comments

Author: frank-at-adacore

courses/ada_essentials/900_gnat_in_practice/01-file_naming_conventions.rst

@@ -6,60 +6,88 @@ File Naming Conventions
 Default File Naming Conventions
 ---------------------------------
 
-.. container:: columns
+* GNAT compiler assumes one compilable entity per file
 
-  .. container:: column
+   * Package specification, subprogram body, etc
+
+* File names should match the name of the compilable entity
 
-    * GNAT compiler assumes one compilable entity per file
+   * Replace **.** with **-**
 
-      * Package specification, subprogram body, etc
+* File extensions describe the usage
 
-    * Filenames should match the name of the compilable entity
+   * **.ads** |rightarrow| Specification / Interface
+   * **.adb** |rightarrow| Body / Implementation
 
-      * Replacing **.** with **-**
-      * File extension is :filename:`.ads` for specifications and :filename:`.adb` for bodies
+---------------------------------
+Example Filenames with Contents
+---------------------------------
+
+.. container:: columns
 
   .. container:: column
 
     .. container:: latex_environment tiny
 
-      :filename:`some_types.ads`
-
       .. code:: Ada
 
          package Some_Types is
             type One_T is new Integer;
             type Two_T is new Character;
-            function Convert
-              (Src : One_T)
-               return Two_T;
+            function Convert (Src : One_T)
+                              return Two_T;
          end Some_Types;
 
-      :color-white:`blank line`
+  .. container:: column
+
+    .. container:: latex_environment tiny
+
+      *Package specification for* :ada:`Some_Types` *is in file* :filename:`some_types.ads`
 
-      :filename:`some_types.adb`
+.. container:: latex_environment tiny
+
+   :color-white:`blank line`
+
+.. container:: columns
+
+  .. container:: column
+
+    .. container:: latex_environment tiny
 
       .. code:: Ada
 
          package body Some_Types is
-            function Convert
-                (Src : One_T)
-                 return Two_T is
-              (Two_T'Val (Integer (Src)));
+            function Convert (Src : One_T)
+                              return Two_T is
+               (Two_T'Val (Integer (Src)));
          end Some_Types;
 
-      :color-white:`blank line`
+  .. container:: column
+
+    .. container:: latex_environment tiny
+
+      *Package body for* :ada:`Some_Types` *is in file* :filename:`some_types.adb`
 
-      :filename:`some_types-child.adb`
+.. container:: latex_environment tiny
+
+   :color-white:`blank line`
+
+.. container:: columns
+
+  .. container:: column
+
+    .. container:: latex_environment tiny
 
       .. code:: Ada
 
-         function Some_Types.Child
-           (Src : Two_T)
-            return One_T is
-         begin
-            return One_T (Two_T'Pos (Src));
-         end Some_Types.Child;
+         function Some_Types.Child (Src : Two_T)
+                                    return One_T;
+
+  .. container:: column
+
+    .. container:: latex_environment tiny
+
+      *Subprogram specification for function* :ada:`Child` *which is a child of* :ada:`Some_Types` *is in file* :filename:`some_types-child.ads`
 
 ---------------------------------------
 Converting to GNAT Naming Conventions
@@ -92,7 +120,7 @@ Using Other Naming Conventions
 
 * Controlled via package :ada:`Naming` in project file
 
-   * Example: your source files use :filename:`.1.ada` for specs and :filename:`.2.ada` for bodies
+   * **Example:** your source files use :filename:`.1.ada` for specs and :filename:`.2.ada` for bodies
 
       .. code:: Ada
 

courses/ada_essentials/900_gnat_in_practice/02-vs_code.rst

@@ -6,14 +6,15 @@ Using VS Code with GNAT
 Setting up VS Code
 --------------------
 
+
 * Need to download and install *Ada & SPARK extensions for VS Code*
 
-   * https://marketplace.visualstudio.com/items?itemName=AdaCore.ada
+   * :url:`Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=AdaCore.ada>`
    * Search for **adacore** in VS Code Extensions (:menu:`Ctrl+Shift+X`)
 
 * Make sure GNAT is installed and on your path
 
-   * If not already downloaded, look here https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada#getting-additional-tools
+   * If not already downloaded, look on :url:`GitHub <https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada\#getting-additional-tools>`
 
 -----------------------------
 Using VS Code with the Labs
@@ -23,7 +24,7 @@ Using VS Code with the Labs
 
   * From a command prompt
 
-     * Navigate the the appropriate folder (:filename:`prompt` or :filename:`answer`)
+     * Navigate to the appropriate folder (:filename:`prompt` or :filename:`answer`)
      * Enter :command:`code .`
 
         * :menu:`Explorer` tree should show :filename:`default.gpr` and Ada file(s)