Update docs for configuring logging formats (espcially for use with ros2 launch)

source/Concepts/Intermediate/About-Logging.rst

@@ -108,6 +108,59 @@ For each of the environment settings, note that this is a process-wide setting,
 
   If no format is given, a default of ``[{severity}] [{time}] [{name}]: {message}`` is used.
 
+``RCUTILS_CONSOLE_OUTPUT_FORMAT`` also supports the following escape character syntax.
+
+.. list-table::
+    :header-rows: 1
+
+    * - Escape character syntax
+      - Character represented
+    * - ``\a``
+      - Alert
+    * - ``\b``
+      - Backspace
+    * - ``\n``
+      - New line
+    * - ``\r``
+      - Carriage return
+    * - ``\t``
+      - Horizontal tab
+    * - ``\x1b``
+      - ANSI escape sequence start
+
+The ANSI escape sequence is especially interesting to use for setting `select graphics rendition parameters <https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters>`_.
+This allows you to format parts of the log message in different styles for better readability.
+See :doc:`Logging Demo <../../Tutorials/Demos/Logging-and-logger-configuration>` for an example.
+
+If ``launch`` is used to start a node, it will also generate output to the console and log.
+This can also be configured using environment variables.
+
+* ``ROS_LAUNCH_OUTPUT_FORMAT`` - Control which extra information is added by ``launch`` to each message comming from a node.
+
+  * ``{line}`` - The log message which is itself formated according to the ``RCUTILS_CONSOLE_OUTPUT_FORMAT``.
+  * ``{this.process_description.final_name}`` - The name of the corresponding logger.
+  * ``{this.process_description.final_cmd}`` - The command that ``launch`` used to start the node.
+
+  If no format is given, a default of ``[{this.process_description.final_name}] {line}`` is used.
+
+* ``OVERRIDE_LAUNCH_PROCESS_OUTPUT`` - Control the destionation of the logging by choosing one of the following options:
+
+  * ``screen`` - ``stdout`` and ``stderr`` are logged to the screen.
+  * ``log`` - ``stdout`` and ``stderr`` are logged to launch log file and ``stderr`` to the screen.
+  * ``both`` - Both ``stdout`` and ``stderr`` are logged to the screen and to launch main log file.
+  * ``own_log`` - For ``stdout``, ``stderr`` and their combination to be logged to their own log files.
+  * ``full`` - To have ``stdout`` and ``stderr`` sent to the screen, to the main launch log file, and their own separate and combined log files.
+
+* ``OVERRIDE_LAUNCH_SCREEN_FORMAT`` - This format is used to display any messages directly comming from ``launch`` (in contrast to the messages coming from nodes).
+
+  * ``{levelname}`` - The severity level (``INFO``, ``WARN``, etc.).
+  * ``{name}`` - The name of the corresponding logger.
+  * ``{message}`` - The actual message.
+  * ``{created:.7f}`` - The time stamp (in this case with seven decimal places).
+
+  If no format is given, a default of ``[{levelname}] [{name}]: {msg}`` is used.
+
+* ``OVERRIDE_LAUNCH_LOG_FORMAT`` - The same as ``OVERRIDE_LAUNCH_SCREEN_FORMAT`` but for writting to the log file. If no format is given, a default of  ``{created:.7f} [{levelname}] [{name}]: {msg}`` is used.
 
 Node creation
 ^^^^^^^^^^^^^

source/Tutorials/Demos/Logging-and-logger-configuration.rst

@@ -406,23 +406,33 @@ For example, to additionally get the timestamp and location of the log calls, st
 You should see the timestamp in seconds and the function name, filename and line number additionally printed with each message.
 *The ``time`` option is only supported as of the ROS 2 Bouncy release.*
 
-``RCUTILS_CONSOLE_OUTPUT_FORMAT`` also supports the following escape character syntax.
-
-.. list-table::
-    :header-rows: 1
-
-    * - Escape character syntax
-      - Character represented
-    * - ``\a``
-      - Alert
-    * - ``\b``
-      - Backspace
-    * - ``\n``
-      - New line
-    * - ``\r``
-      - Carriage return
-    * - ``\t``
-      - Horizontal tab
+It is also possible to change the font style of the different message parts using select graphic rendition parameters.
+For example, to print the node name underlined, the message bold, and the function name faint you can use the following setting:
+
+.. tabs::
+
+  .. group-tab:: Linux
+
+    .. code-block:: bash
+
+      export RCUTILS_CONSOLE_OUTPUT_FORMAT="\x1b[4m{name}\x1b[0m \x1b[1m{message}\x1b[0m \x1b[2m{function_name}\x1b[0m"
+      ros2 run logging_demo logging_demo_main
+
+  .. group-tab:: macOS
+
+    .. code-block:: bash
+
+      export RCUTILS_CONSOLE_OUTPUT_FORMAT="\x1b[4m{name}\x1b[0m \x1b[1m{message}\x1b[0m \x1b[2m{function_name}\x1b[0m"
+      ros2 run logging_demo logging_demo_main
+
+  .. group-tab:: Windows
+
+    .. code-block:: bash
+
+      set "RCUTILS_CONSOLE_OUTPUT_FORMAT=\x1b[4m{name}\x1b[0m \x1b[1m{message}\x1b[0m \x1b[2m{function_name}\x1b[0m"
+      ros2 run logging_demo logging_demo_main
+
+See :doc:`Logging and logger configuration <../../Concepts/Intermediate/About-Logging>` for more details on how to configure the logging.
 
 Console output colorizing
 ^^^^^^^^^^^^^^^^^^^^^^^^^