publish idl articles, add note to existing articles (#215)

* publish idl articles, add note to existing articles

* add short text to empty sections

* mention annotations

articles/110_interface_definition.md

@@ -13,6 +13,10 @@ categories: Interfaces
 
 # {{ page.title }}
 
+<div class="alert alert-warning" markdown="1">
+With the transition to use ``IDL`` for specifying interfaces in ROS 2 Dashing this article has been superseded by the [legacy interface definition](legacy_interface_definition.html) article.
+</div>
+
 <div class="abstract" markdown="1">
 {{ page.abstract }}
 </div>

articles/111_mapping_dds_types.md

@@ -13,6 +13,10 @@ categories: Interfaces
 
 # {{ page.title }}
 
+<div class="alert alert-warning" markdown="1">
+With the transition to use ``IDL`` for specifying interfaces in ROS 2 Dashing this article has been superseded by the [legacy interface definition](legacy_interface_definition.html) article.
+</div>
+
 <div class="abstract" markdown="1">
 {{ page.abstract }}
 </div>

articles/112_generated_interfaces_cpp.md

@@ -13,6 +13,10 @@ categories: Interfaces
 
 # {{ page.title }}
 
+<div class="alert alert-warning" markdown="1">
+With the transition to use ``IDL`` for specifying interfaces in ROS 2 Dashing this article has been superseded by the [Interface Definition and Language Mapping](idl_interface_definition.html) article.
+</div>
+
 <div class="abstract" markdown="1">
 {{ page.abstract }}
 </div>

articles/114_generated_interfaces_python.md

@@ -13,6 +13,10 @@ categories: Interfaces
 
 # {{ page.title }}
 
+<div class="alert alert-warning" markdown="1">
+With the transition to use ``IDL`` for specifying interfaces in ROS 2 Dashing this article has been superseded by the [Interface Definition and Language Mapping](idl_interface_definition.html) article.
+</div>
+
 <div class="abstract" markdown="1">
 {{ page.abstract }}
 </div>

articles/142_idl.md

@@ -4,7 +4,7 @@ title: IDL - Interface Definition and Language Mapping
 permalink: articles/idl_interface_definition.html
 abstract:
   This describes defining interfaces using a subset of the [Interface Definition Language](https://www.omg.org/spec/IDL/) (IDL).
-published: false
+published: true
 author: '[Dirk Thomas](https://github.com/dirk-thomas)'
 categories: Interfaces
 ---
@@ -32,6 +32,26 @@ Further it describes how the interfaces are used to generate code in C, C++ and
 
 ROS 2 supports a subset of the [OMG IDL 4.2 specification](https://www.omg.org/spec/IDL/4.2).
 
+### Lexical Conventions
+
+#### 7.2.2 Comments
+
+Both line comments (`//`) as well as block comments (`/* ... */`) are being supported.
+
+#### 7.2.3 Identifiers
+
+An identifier must start with an is an ASCII alphabetic characteran followed by any number of ASCII alphabetic, digit and underscore (`_`) characters.
+
+#### 7.2.6 Literals
+
+All of the following literals are supported:
+
+- Integer
+- Character
+- String
+- Floating-point
+- Fixed-point
+
 ### Basic Types
 
 #### 7.4.1.4.4.2.1 Integer Types
@@ -139,6 +159,11 @@ An enumerated type consist of an ordered list of enumerators.
 A multidimensional, fixed-size array is defined by the type of each item and the explicit sizes for each dimension.
 For now only a one-dimensional, fixed-size array is supported though.
 
+### Annotations
+
+The syntax for arbitrary annotations is supported.
+How each annotation type is being handled depends on the code generation described below.
+
 ## Code Generation
 
 <div class="alert alert-warning" markdown="1">
@@ -206,3 +231,17 @@ If a cell is blank then the default mapping is used.
 | octet[N]                     |   | -                                 | -              | bytes                                           | |
 | sequence\<octet>              |   | -                                 | -              | bytes                                           | |
 | sequence<octet, N>           |   | -                                 | -              | bytes                                           | |
+
+### Standardized Annotations
+
+#### 8.3.2.1 @key Annotation
+
+While the key annotation doesn't affect the generated ROS data types directly it is being passed through to the (DDS) vendor specific code generators.
+
+#### 8.3.3.1 @default Annotation
+
+The default value is being used to initialize struct members.
+
+#### 8.3.5.1 @verbatim Annotation
+
+When the value `comment` is passed as the `language` parameter the text parameter is used as the docblock for the annotated element across all supported programming languages.

articles/143_legacy_interface_definition.md

@@ -1,10 +1,10 @@
 ---
 layout: default
-title: Interface definition
+title: Legacy interface definition using .msg / .srv / .action files
 permalink: articles/legacy_interface_definition.html
 abstract:
-  This article specifies the file format describing the data structures exchanged by ROS 2 components to interact with each other.
-published: false
+  This article specifies the file format coming from ROS 1 describing the data structures exchanged by ROS components to interact with each other.
+published: true
 author: '[Dirk Thomas](https://github.com/dirk-thomas)'
 categories: Interfaces
 ---
@@ -21,10 +21,12 @@ Original Author: {{ page.author }}
 
 ## Scope
 
-This article specifies the file format describing the data structures which are being used to exchange information between components.
+This article specifies the legacy file format describing the data structures which are being used to exchange information between components.
 The data structures are defined in a programming language agnostic way.
 The format is based on the [<code>.msg</code> format definition](http://wiki.ros.org/msg#Message_Description_Specification) from ROS 1.
-Please see other articles for the mappings to programming language specific types and API.
+
+Below only the mapping to IDL types is described.
+Please see the [Interface Definition and Language Mapping](idl_interface_definition.html) article for the mappings to programming language specific types and API.
 
 ## Overview
 
@@ -259,7 +261,7 @@ A service file contains two message definitions which are separated by a line wh
 
 ## Conversion to IDL
 Code is generated for defined interfaces to be usable by different client libraries.
-Interfaces described using the legacy format are first converted to [IDL](articles/idl_interface_definition.html).
+Interfaces described using the legacy format are first converted to [IDL](idl_interface_definition.html).
 Code generation uses the generated file.
 
 ### Mapping to IDL types