Switch to 'let' under 'include' tags for launch frontends (#5923) (#5926)

(cherry picked from commit 51e6598)

Signed-off-by: Christophe Bedard <[email protected]>
Co-authored-by: Christophe Bedard <[email protected]>

Author: mergify[bot]

source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst

@@ -186,7 +186,9 @@ include
      Nest includes in ``group`` tags to scope them.
    * ``ns`` attribute is not supported.
      See example of ``push_ros_namespace`` tag for a workaround.
-   * ``arg`` tags nested in an ``include`` tag don't support conditionals (``if``, ``unless``) or the ``description`` attribute.
+   * ``arg`` tag nested in an ``include`` tag is now ``let``.
+     However, ``arg`` is still supported for now.
+   * ``let`` tags nested in an ``include`` tag don't support conditionals (``if``, ``unless``) or the ``description`` attribute.
    * There is no support for nested ``env`` tags.
      ``set_env`` and ``unset_env`` can be used instead.
    * Both ``clear_params`` and ``pass_all_args`` attributes aren't supported.
@@ -206,7 +208,10 @@ arg
    * ``value`` attribute is not allowed.
      Use ``let`` tag for this.
    * ``doc`` is now ``description``.
-   * When nested within an ``include`` tag, ``if``, ``unless``, and ``description`` attributes aren't allowed.
+   * When nested within an ``include`` tag:
+
+      * Use ``let`` instead of ``arg``.
+      * ``if``, ``unless``, and ``description`` attributes aren't allowed.
 
 Example
 ~~~~~~~
@@ -351,6 +356,13 @@ It's a replacement of ``arg`` tag with a value attribute.
 
    <let name="foo" value="asd"/>
 
+``let`` and ``arg`` serve two different purposes in ROS 2:
+
+* ``let`` sets a launch configuration value.
+* ``arg`` declares a launch argument/configuration and optionally provides a default value.
+  The value can separately be set from the CLI or when including the given launch file.
+  If no value is set, the default value is used if one was provided, otherwise an error is reported.
+
 executable
 ^^^^^^^^^^
 

source/Tutorials/Intermediate/Launch/launch/example_main_launch.xml

@@ -2,8 +2,8 @@
 <launch>
   <let name="background_r" value="200" />
   <include file="$(find-pkg-share launch_tutorial)/launch/example_substitutions_launch.xml">
-    <arg name="turtlesim_ns" value="turtlesim2" />
-    <arg name="use_provided_red" value="True" />
-    <arg name="new_background_r" value="$(var background_r)" />
+    <let name="turtlesim_ns" value="turtlesim2" />
+    <let name="use_provided_red" value="True" />
+    <let name="new_background_r" value="$(var background_r)" />
   </include>
 </launch>

source/Tutorials/Intermediate/Launch/launch/example_main_launch.yaml

@@ -6,7 +6,7 @@ launch:
       value: "200"
   - include:
       file: "$(find-pkg-share launch_tutorial)/launch/example_substitutions_launch.yaml"
-      arg:
+      let:
         - name: "turtlesim_ns"
           value: "turtlesim2"
         - name: "use_provided_red"