Allow include: to take a single text element instead of requiring file:

[emersonknapp]

Closes robograph-project/planning#15

Not sure this has to be in launch, but it's part of an ergonomics sweep I'm doing while writing more YAML/XML launchfiles.

I felt that for simple actions, it made sense to be able to just pass the single argument as a bare text element to the action, rather than requiring a list or dict contents.

Specifically, the following felt obvious, but was not supported, and probably makes sense for some other Actions.

---
# Before
launch:
  - include:
      file: $(find-pkg-share pkg)/launch/my_launch.yaml
      
# After
launch:
  - include: $(find-pkg-share pkg)/launch/my_launch.yaml

# Before
<launch>
  <include file="$(find-pkg-share pkg)/launch/my_launch.xml"/>
<launch>

# After
<launch>
  <include>$(find-pkg-share pkg)/launch/my_launch.xml</include>
</launch>

Admittedly, the XML one is actually more verbose, it's a bigger improvement for simple YAML.

This is a complete enhancement PR with unit tests for the new feature, if others agree that this makes sense.

Argument for: This matches the Python API more directly since IncludeLaunchDescription takes a non-keyword first argument for the launch_description_source. It also allows for shorter, clearer launchfiles for simple usage

Argument against: most real usage has other attributes, arg etc, allowing this simple syntax could make things more confusing by having multiple ways of doing things.

[emersonknapp]

Discussed in PMC meeting today. Fielded some agreement with the concern that it's "one more way to do things", but also no strong objection either. Relatively neutral.

@tfoote brought up that we may want to support file:// or https:// etc URIs in include, in the future. That's interesting, I don't think that this synax precludes it. May be more of a text interpretation thing than a new attribute, anyways.

[ros-discourse]

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/ros-2-pmc-meeting-minutes-for-april-29-2025/43451/1

[emersonknapp]

@wjwwood @christophebedard @ahcorde could I get your thoughts on this one? I still think it's a good idea, but I'd like us to decide one way or the other. Either move forward, or decide that we don't want this.

[emersonknapp]

Like discussed, there is a benefit to having a really explicit data model.

For YAML that data model translates to these terms (XML has the same structure but uses slightly different terms based on its syntax):

1. Launch is specified as a tree of Actions - which renders out to a flat list of processes to run
   1a. launch is the top level Action
2. An Action is a single-key mapping containing one mapping of one or more keys, called "Attributes"
   2a. Attributes may take text, mapping, or list
   2b. There is a special-case Attribute named children, which takes a homogenous list of mappings, and if no other Attributes are required, the children can be provided as a list directly to the parent Action

This proposal I believe boils down to changing 2b. to something like:

"2b. Some Actions have a special case 'default attribute key' such that if no other attributes are needed, you can provide a value directly - which may be text, mapping, or list depending on the attribute. For example, in group: this is children which is a list of Actions, and for include: this is file"

Which to me makes as much sense as the children special case. In the launch Python API, this is actually already the case, as most Actions take one or more non-keyword arguments to the constructor. And they do not have children as an argument, instead naming that attribute something more specific, like GroupAction(actions: Iterable[Action], ...)

[christophebedard]

I agree that - include: $file in YAML makes a lot of sense for the reasons you described. It does limit us to a single "bare text" value, which makes sense for the include action. Do you plan to apply this to other actions? I guess we can just apply this to actions where choosing the single "bare text" parameter/argument is trivial (e.g., namespace for PushROSNamespace, arg name for DeclareLaunchArgument), and leave the rest alone.

The only thing I'm not that happy about is having another way of providing the file to the include action, which you did mention. How do we avoid confusing users? Especially since no other (YAML) action currently has both a "bare text" value and child entities. I'd like to see documentation, both (1) in this PR and (2) to go along with this PR:

1. YAML/XML/Python examples in the IncludeLaunchDescription class docstring, like I've been adding to other action classes
2. docs.ros.org: update some (or all?) YAML examples to use this:
   1. https://docs.ros.org/en/rolling/Tutorials/Intermediate/Launch/Using-Substitutions.html
   2. https://docs.ros.org/en/rolling/How-To-Guides/Launch-file-different-formats.html
   3. (Not https://docs.ros.org/en/rolling/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.html#replacing-an-include-tag, because it only contains XML examples "for an easy migration from ROS 1")
   4. Anywhere else?

[christophebedard]

Can we find a more descriptive name for this, or just describe it using words other than "bare text" in the docstring, so that it's a bit clearer?

[emersonknapp]

yeah, a different name is fine, i just wasn't sure what to call it exactly