Fine-tune documentation of new CONSOLE pseudo log level.

Related to #4536.

doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.rst

@@ -2166,11 +2166,12 @@ Using log levels
 
 To use other log levels than `INFO`, or to create several
 messages, specify the log level explicitly by embedding the level into
-the message in the format `*LEVEL* Actual log message`, where
-`*LEVEL*` must be in the beginning of a line and `LEVEL` is
-one of the available logging levels `TRACE`, `DEBUG`,
-`INFO`, `WARN`, `ERROR`, `HTML` and `CONSOLE`. Log level `CONSOLE`
-is new in Robot Framework 6.1.
+the message in the format `*LEVEL* Actual log message`.
+In this formant `*LEVEL*` must be in the beginning of a line and `LEVEL`
+must be one of the available concrete log levels `TRACE`, `DEBUG`,
+`INFO`, `WARN` or `ERROR`, or a pseudo log level `HTML` or `CONSOLE`.
+The pseudo levels can be used for `logging HTML`_ and `logging to console`_,
+respectively.
 
 Errors and warnings
 '''''''''''''''''''
@@ -2235,12 +2236,23 @@ __ `Using log levels`_
 Logging to console
 ''''''''''''''''''
 
-If libraries need to write something to the console they have several
-options. As already discussed, warnings and all messages written to the
+Libraries have several options for writing messages to the console.
+As already discussed, warnings and all messages written to the
 standard error stream are written both to the log file and to the
 console. Both of these options have a limitation that the messages end
-up to the console only after the currently executing keyword
-finishes.
+up to the console only after the currently executing keyword finishes.
+
+Starting from Robot Framework 6.1, libraries can use a pseudo log level
+`CONSOLE` for logging messages *both* to the log file and to the console:
+
+.. sourcecode:: python
+
+   def my_keyword(arg):
+       print('*CONSOLE* Message both to log and to console.')
+
+These messages will be logged to the log file using the `INFO` level similarly
+as with the `HTML` pseudo log level. When using this approach, messages
+are logged to the console only after the keyword execution ends.
 
 Another option is writing messages to `sys.__stdout__` or `sys.__stderr__`.
 When using this approach, messages are written to the console immediately
@@ -2252,20 +2264,21 @@ and are not written to the log file at all:
 
 
    def my_keyword(arg):
-      sys.__stdout__.write('Got arg %s\n' % arg)
+       print('Message only to console.', file=sys.__stdout__)
 
-The final option is using the `public logging API`_:
+The final option is using the `public logging API`_. Also in with this approach
+messages are written to the console immediately:
 
 .. sourcecode:: python
 
    from robot.api import logger
 
 
    def log_to_console(arg):
-      logger.console('Got arg %s' % arg)
+       logger.console('Message only to console.')
 
    def log_to_console_and_log_file(arg):
-      logger.info('Got arg %s' % arg, also_console=True)
+       logger.info('Message both to log and to console.', also_console=True)
 
 Logging example
 '''''''''''''''

src/robot/api/logger.py

@@ -74,13 +74,12 @@ def my_keyword(arg):
 def write(msg, level='INFO', html=False):
     """Writes the message to the log file using the given level.
 
-    Valid log levels are ``TRACE``, ``DEBUG``, ``INFO`` (default), ``WARN``, and
-    ``ERROR``. Additionally there are two pseudo log levels: ``HTML``and ``CONSOLE``.
-    ``HTML`` pseudo log level logs the message as HTML using the ``INFO`` level.
-    ``CONSOLE`` pseudo log level logs the message to stdout and to the log file
-    using ``INFO`` level. Pseudo log levels are are converted to ``INFO`` level if
-    Robot Framework is not running when calling this function.
-    Log level ``CONSOLE`` is new in Robot Framework 6.1.
+    Valid log levels are ``TRACE``, ``DEBUG``, ``INFO`` (default), ``WARN``,
+    and ``ERROR``. In addition to that, there are pseudo log levels ``HTML``
+    and ``CONSOLE`` for logging messages as HTML and for logging messages
+    both to the log file and to the console, respectively. With both of these
+    pseudo levels the level in the log file will be ``INFO``. The ``CONSOLE``
+    level is new in Robot Framework 6.1.
 
     Instead of using this method, it is generally better to use the level
     specific methods such as ``info`` and ``debug`` that have separate

src/robot/libraries/BuiltIn.py

@@ -2976,31 +2976,31 @@ def log(self, message, level='INFO', html=False, console=False,
             repr='DEPRECATED', formatter='str'):
         r"""Logs the given message with the given level.
 
-        Valid levels are TRACE, DEBUG, INFO (default), CONSOLE, HTML, WARN, and ERROR.
-        Messages below the current active log level are ignored. See
-        `Set Log Level` keyword and ``--loglevel`` command line option
-        for more details about setting the level.
-        Log level CONSOLE is new in Robot Framework 6.1.
+        Valid levels are TRACE, DEBUG, INFO (default), WARN and ERROR.
+        In addition to that, there are pseudo log levels HTML and CONSOLE that
+        both log messages using INFO.
 
-        Messages logged with the WARN or ERROR levels will be automatically
+        Messages below the current active log
+        level are ignored. See `Set Log Level` keyword and ``--loglevel``
+        command line option for more details about setting the level.
+
+        Messages logged with the WARN or ERROR levels are automatically
         visible also in the console and in the Test Execution Errors section
         in the log file.
 
         If the ``html`` argument is given a true value (see `Boolean
-        arguments`), the message will be considered HTML and special characters
+        arguments`) or the HTML pseudo log level is used, the message is
+        considered to be HTML and special characters
         such as ``<`` are not escaped. For example, logging
-        ``<img src="image.png">`` creates an image when ``html`` is true, but
-        otherwise the message is that exact string. An alternative to using
-        the ``html`` argument is using the HTML pseudo log level. It logs
-        the message as HTML using the INFO level.
-
-        If the ``console`` argument is true or the log level is ``CONSOLE``,
-        the message will be written to the console where test execution was
-        started from in addition to the log file. This keyword always uses the
-        standard output stream and adds a newline after the written message.
-        Use `Log To Console` instead if either of these is undesirable,
-    Mimic html section...
-        
+        ``<img src="image.png">`` creates an image in this case, but
+        otherwise the message is that exact string. When using the HTML pseudo
+        level, the messages is logged using the INFO level.
+
+        If the ``console`` argument is true or the CONSOLE pseudo level is
+        used, the message is written both to the console and to the log file.
+        When using the CONSOLE pseudo level, the message is logged using the
+        INFO level. If the message should not be logged to the log file or there
+        are special formatting needs, use the `Log To Console` keyword instead.
 
         The ``formatter`` argument controls how to format the string
         representation of the message. Possible values are ``str`` (default),
@@ -3028,6 +3028,7 @@ def log(self, message, level='INFO', html=False, console=False,
         `Log To Console` if you only want to write to the console.
 
         Formatter options ``type`` and ``len`` are new in Robot Framework 5.0.
+        The CONSOLE level is new in Robot Framework 6.1.
         """
         # TODO: Remove `repr` altogether in RF 7.0. It was deprecated in RF 5.0.
         if repr == 'DEPRECATED':