Merge branch 'docs/autocolor_multiline_v5.5' into 'release/v5.5'

docs(tools/idf-monitor): Add note about autocoloring limitation on multiline logs (v5.5)

See merge request espressif/esp-idf!39145

components/log/Kconfig.format

@@ -8,6 +8,9 @@ menu "Format"
             Enable ANSI terminal color codes. Logs (info, errors, warnings) will contain color codes.
             In order to view these, your terminal program must support ANSI color codes.
 
+            This is disabled by default, as colors are added in IDF Monitor. If you want to use new lines
+            in the messages or you are using a different terminal program, you may want to enable this option.
+
     config LOG_COLORS_SUPPORT
         bool "Allow enabling color output at run time"
         depends on LOG_VERSION_2

docs/en/api-guides/tools/idf-monitor.rst

@@ -34,22 +34,22 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
      -
    * - * Ctrl + P
      - Reset target into bootloader to pause app via RTS and DTR lines
-     - Resets the target into the bootloader using the RTS and DTR lines (if connected). This stops the board from executing the application, making it useful when waiting for another device to start. For additional details, refer to :ref:`target-reset-into-bootloader`.
+     - Reset the target into the bootloader using the RTS and DTR lines (if connected). This stops the board from executing the application, making it useful when waiting for another device to start. For additional details, refer to :ref:`target-reset-into-bootloader`.
    * - * Ctrl + R
      - Reset target board via RTS
-     - Resets the target board and re-starts the application via the RTS line (if connected).
+     - Reset the target board and re-starts the application via the RTS line (if connected).
    * - * Ctrl + F
      - Build and flash the project
-     - Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. Target ``encrypted-flash`` is run if idf_monitor was started with argument ``-E``.
+     - Pause idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. Target ``encrypted-flash`` is run if idf_monitor was started with argument ``-E``.
    * - * Ctrl + A (or A)
      - Build and flash the app only
-     - Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. Target ``encrypted-app-flash`` is run if idf_monitor was started with argument ``-E``.
+     - Pause idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. Target ``encrypted-app-flash`` is run if idf_monitor was started with argument ``-E``.
    * - * Ctrl + Y
      - Stop/resume log output printing on screen
-     - Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor.
+     - Discard all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor.
    * - * Ctrl + L
      - Stop/resume log output saved to file
-     - Creates a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits).
+     - Create a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits).
    * - * Ctrl + I (or I)
      - Stop/resume printing timestamps
      - IDF Monitor can print a timestamp in the beginning of each line. The timestamp format can be changed by the ``--timestamp-format`` command line argument.
@@ -61,11 +61,27 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
      -
    * - Ctrl + C
      - Interrupt running application
-     - Pauses IDF Monitor and runs GDB_ project debugger to debug the application at runtime. This requires :ref:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` option to be enabled.
+     - Pause IDF Monitor and runs GDB_ project debugger to debug the application at runtime. This requires :ref:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` option to be enabled.
 
 Any keys pressed, other than ``Ctrl-]`` and ``Ctrl-T``, will be sent through the serial port.
 
 
+Automatic Coloring
+==================
+
+IDF Monitor automatically colors the output based on the log level. This feature reduces the number of bytes transferred over the serial console by avoiding redundant log formatting, which can improve performance by reducing latency in log transmission. Other benefits include adding colors to precompiled libraries (such as Wi-Fi) and reduced binary size of the application.
+
+The automatic coloring is enabled by default. To disable it, use the command line option ``--disable-auto-color``.
+
+The coloring is done based on the log level followed by optional timestamp and tag. For option to enable coloring on the {IDF_TARGET_NAME} side, see :ref:`CONFIG_LOG_COLORS`.
+
+For more details on the log, see :doc:`Logging <../../api-reference/system/log>`.
+
+.. note::
+
+    The automatic coloring will not work properly if the message contains new lines. In this case the IDF Monitor will only color the first line of the message.
+
+
 ESP-IDF-specific Features
 =========================
 
@@ -351,6 +367,10 @@ Known Issues with IDF Monitor
 
 The following issues are currently known:
 
+- Autocoloring cannot detect the log level if the message contains new lines. In this case, the IDF Monitor will only color the first line of the message.
+
+  To work around this issue, enable :ref:`CONFIG_LOG_COLORS` in menuconfig. Please note that this might have some impact on binary size and performance.
+
 - On Windows, if the terminal is closed without first closing the IDF Monitor, some drivers may fail to release the serial port. To release the port, you may need to unplug and replug the USB cable, or in some cases even restart the computer. This issue has been observed with the CH9102 USB-to-UART bridge. Other drivers, such as CP210x and CH340, should work fine.
 
   To prevent this issue, make sure to close the IDF Monitor properly before exiting the terminal, or consider using an alternative USB-to-UART bridge.

docs/zh_CN/api-guides/tools/idf-monitor.rst

@@ -61,11 +61,27 @@ IDF 监视器是一个串行终端程序，使用了 esp-idf-monitor_ 包，用
      -
    * - Ctrl + C
      - 中断正在运行的应用程序
-     - 暂停 IDF 监视器并运行 GDB_ 项目调试器，从而在运行时调试应用程序。这需要启用 :ref: `CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` 选项。
+     - 暂停 IDF 监视器并运行 GDB_ 项目调试器，从而在运行时调试应用程序。这需要启用 :ref:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` 选项。
 
 除了 ``Ctrl-]`` 和 ``Ctrl-T``，其他快捷键信号会通过串口发送到目标设备。
 
 
+自动着色
+==========
+
+IDF 监视器会根据日志级别自动为输出内容进行着色。该功能通过避免冗余的日志格式化，减少了通过串口控制台传输的字节数，降低了日志传输的延迟，提升了性能。该功能还具有其他优势，能够为预编译库（例如 Wi-Fi）添加颜色，以及减少应用程序的二进制文件大小。
+
+该功能默认启用。如需禁用，请使用命令行选项 ``--disable-auto-color``。
+
+着色是基于日志级别进行的，日志级别后可选择是否显示时间戳和标签。如需在 {IDF_TARGET_NAME} 端启用着色，参见 :ref:`CONFIG_LOG_COLORS`。
+
+有关日志的更多信息，参见 :doc:`日志记录 <../../api-reference/system/log>`。
+
+.. note::
+
+    如果日志消息中包含换行符，自动着色可能无法正常工作。在这种情况下，IDF 监视器仅会为消息的第一行着色。
+
+
 兼具 ESP-IDF 特性
 =========================
 
@@ -351,6 +367,10 @@ IDF 监视器已知问题
 
 目前已知的问题如下：
 
+- 消息中包含换行符时，自动着色无法检测日志级别。在这种情况下，IDF Monitor 只会为消息的第一行着色。
+
+  为了避免这个问题，可以在 menuconfig 中启用 :ref:`CONFIG_LOG_COLORS`。注意，这可能会对二进制文件的大小和性能产生一定影响。
+
 - 在 Windows 上，如果在 IDF 监视器关闭之前直接关闭了终端，某些驱动程序可能无法释放串口。要解决此问题，可以尝试重新拔插 USB 线，在某些情况下，需要重启计算机。目前，已知该问题会影响 CH9102 USB-to-UART 桥接芯片，而 CP210x 和 CH340 等驱动通常不会受到影响。
 
   为避免该问题，请在退出终端前正确关闭 IDF 监视器，或考虑使用其他 USB-to-UART 桥接芯片。