Merge branch 'mr/320-new_hello_world_module' into 'master'

Resolve "Extract the "Hello World" Setup from the Overview Module"

Closes #320

See merge request feng/training/material!386

Author: frank-at-adacore

courses/ada_essentials/010_overview.rst

@@ -42,4 +42,3 @@ Overview
 
 .. include:: 010_overview/01-a_little_history.rst
 .. include:: 010_overview/02-big_picture.rst
-.. include:: 010_overview/03-setup.rst

courses/ada_essentials/013_hello_world.rst

@@ -0,0 +1,41 @@
+**************
+Hello World!
+**************
+
+.. container:: PRELUDE BEGIN
+
+.. container:: PRELUDE ROLES
+
+.. role:: ada(code)
+    :language: Ada
+
+.. role:: C(code)
+    :language: C
+
+.. role:: cpp(code)
+    :language: C++
+
+.. role:: rust(code)
+    :language: Rust
+
+.. container:: PRELUDE SYMBOLS
+
+.. |rightarrow| replace:: :math:`\rightarrow`
+.. |forall| replace:: :math:`\forall`
+.. |exists| replace:: :math:`\exists`
+.. |equivalent| replace:: :math:`\iff`
+.. |le| replace:: :math:`\le`
+.. |ge| replace:: :math:`\ge`
+.. |lt| replace:: :math:`<`
+.. |gt| replace:: :math:`>`
+.. |checkmark| replace:: :math:`\checkmark`
+
+.. container:: PRELUDE REQUIRES
+
+.. container:: PRELUDE PROVIDES
+
+.. container:: PRELUDE END
+
+.. include:: 013_hello_world/01-canonical_first_program.rst
+.. include:: 013_hello_world/88-lab.rst
+.. include:: 013_hello_world/99-summary.rst

courses/ada_essentials/013_hello_world/01-canonical_first_program.rst

@@ -0,0 +1,84 @@
+=================
+Introducing Ada
+=================
+
+-------------------------
+Canonical First Program
+-------------------------
+
+"Hello World" - written in Ada!
+
+.. container:: overlay 1
+
+   .. image:: hello_world_0.svg
+
+.. container:: overlay 2
+
+   .. image:: hello_world_1.svg
+
+.. container:: overlay 3
+
+   .. image:: hello_world_2.svg
+
+.. container:: overlay 4
+
+   .. image:: hello_world_3.svg
+
+.. container:: overlay 5
+
+   .. image:: hello_world_4.svg
+
+.. container:: overlay 6
+
+   .. image:: hello_world_5.svg
+
+.. container:: overlay 7
+
+   .. image:: hello_world_6.svg
+
+.. container:: animate 2-
+
+   * :ada:`with` - package dependency (similar to ``import`` or ``#include``)
+
+.. container:: animate 3-
+
+   * :ada:`--` - Comment (always goes to end of line)
+
+.. container:: animate 4-
+
+   * :ada:`procedure` - subprogram declaration (name of subprogram is ``Hello_World``)
+
+.. container:: animate 5-
+
+   * :ada:`begin` - used to start a block of statements
+
+.. container:: animate 6-
+
+   * :ada:`Ada.Text_IO.Put_Line` is a subprogram that prints a string (it's defined
+     in the package we specified on line 1)
+
+.. container:: animate 7-
+
+   * :ada:`end` - used to end a block of statements. It's optional to add the
+     name of the block you are ending
+
+--------------------------------------
+Note on GNAT File Naming Conventions
+--------------------------------------
+
+* GNAT compiler assumes one compilable entity per file
+
+  * Package specification, subprogram body, etc
+  * So the body for :ada:`hello_world` should be the only thing in the file
+
+* Filenames should match the name of the compilable entity
+
+  * Replacing "." with "-"
+  * File extension is ".ads" for specifications and ".adb" for bodies
+  * So the body for :ada:`hello_world` will be in :filename:`hello_world.adb`
+
+    * If there was a specification for the subprogram, it would be in :filename:`hello_world.ads`
+
+* This is the **default** behavior. There are ways around both of these rules
+
+  * For further information, see Section 3.3 *File Naming Topics and Utilities* in the **GNAT User's Guide**

courses/ada_essentials/013_hello_world/88-lab.rst

@@ -0,0 +1,110 @@
+========
+Lab
+========
+
+-----------------
+Hello World Lab
+-----------------
+
+* This lab focuses more on running labs and verifying your setup
+
+   * Goal for this lab is to write an application that says :command:`Hello, World`
+
+* Almost all our labs are the same. In each lab, we will
+
+   * Copy the appropriate :filename:`prompt` directory
+   * Open the project that you just copied over
+   * Make the changes necessary to perform the lab
+   * Compile and run the lab
+   * Compare the actual results to the expected results
+   * Refer to the :filename:`answer` directory if you need help
+
+* This particular lab will walk you through those steps
+
+--------------------------
+Step 1 - Copy the Prompt
+--------------------------
+
+* You should have downloaded (or received) a :filename:`labs`
+  folder
+
+   * This folder contains a directory for each module in the
+     class that has a lab
+
+* In each module directory, you should find a :filename:`prompt`
+  and :filename:`answer` folder
+
+* The :filename:`prompt` folder contains
+
+   * Project file (:filename:`default.gpr`) that instructs
+     the compilation system on how to build the application
+   * Ada file(s) containing the source code for the application
+
+* Create a folder for this class. As you do each lab, copy
+  the module directory into the class folder
+
+---------------------------
+Step 2 - Open the Project
+---------------------------
+
+Using :toolname:`GNAT Studio`
+
+   * If :toolname:`GNAT Studio` is on your path, you can either
+
+      * Double-click the :filename:`default.gpr` project file
+      * Run :command:`gnatstudio default.gpr` file from a command prompt in the correct folder
+
+   * Open the :toolname:`GNAT Studio` application
+
+      * :menu:`File` |rightarrow| :menu:`Open Project` to open the project file
+
+-------------------------------------
+Step 3 - Make the Necessary Changes
+-------------------------------------
+
+* In the left pane (**Project** tab if it not selected), expand the triangles until you
+  see :filename:`hello_world.adb` - double-click it
+
+* In our example, we want to follow the "prompt" comment on line 5
+
+   * On line 6, replace ``<something>`` with ``Hello, World``
+
+----------------------------------
+Step 4 - Compile and Run the Lab
+----------------------------------
+
+.. image:: compile_and_build_buttons.jpg
+
+   *(also available from* :menu:`Build` *menu)*
+
+* After execution, search for the :menu:`Run` tab on the **Messages** window
+
+-------------------------------------
+Step 5 - Compare Actual to Expected
+-------------------------------------
+
+* If the actual results match the goal of the lab
+
+   * Congratulations - you've done it!
+   * In this lab, we should see :command:`Hello, World` in the :menu:`Run` tab
+
+* If they don't, go back to Step 3
+
+   * Or go on to Step 6
+
+--------------------------------
+Step 6 - Looking at the Answer
+--------------------------------
+
+* In the :filename:`answer` folder will be the source code for **a** correct solution
+
+   * Look at the part you think is most likely wrong
+
+      * Then go to Step 3 and see if that hint helps
+
+   * Continue until you get the expected result
+
+      * Even if that means copying the whole answer so you can understand it
+
+* Even when you got it right yourself, looking at the answer may give you another
+  method of solving the problem

courses/ada_essentials/013_hello_world/99-summary.rst

@@ -0,0 +1,20 @@
+=========
+Summary
+=========
+
+----------------------------
+First Steps in Writing Ada
+----------------------------
+
+* **Hello, World** in Ada is just as simple as any other language
+
+  * Semantics and Syntax may be different, but concepts are similar
+
+* We’ve taken the first step in speaking about some common concepts in Ada’s own language
+
+   * Comments
+   * Subprograms
+   * Code blocks
+   * Input/Output (OK, only output so far!)
+
+* On to the real work!

courses/ada_essentials/013_hello_world/lab/hello_world/answer/hello_world.adb

@@ -0,0 +1,7 @@
+--  Everyone's first program
+with Ada.Text_IO;
+procedure Hello_World is
+begin
+   --  Replace '<something>' with 'Hello, World'
+   Ada.Text_IO.Put_Line ("Hello, World");
+end Hello_World;

courses/ada_essentials/013_hello_world/lab/hello_world/prompt/default.gpr

@@ -0,0 +1,3 @@
+project Default is
+   for Main use ("hello_world.adb");
+end Default;

courses/ada_essentials/013_hello_world/lab/hello_world/prompt/hello_world.adb

@@ -0,0 +1,7 @@
+--  Everyone's first program
+with Ada.Text_IO;
+procedure Hello_World is
+begin
+   --  Replace '<something>' with 'Hello, World'
+   Ada.Text_IO.Put_Line ("<something>");
+end Hello_World;

courses/ada_essentials/standard_course.txt

@@ -1,5 +1,6 @@
 005_introduction.rst
 010_overview.rst
+013_hello_world.rst
 015_type_model.rst
 020_declarations.rst
 030_scalar_types.rst