UG: Clarify \n in documentation paragraphs. Fixes
@@ -31,8 +31,13 @@ to test suites, newlines can be added manually using `\n` `escape sequence`_.
.. sourcecode:: robotframework
*** Settings ***
- Documentation First line.\n\nSecond paragraph, this time\nwith multiple lines.
- Metadata Example Value\nin two lines
+ Documentation First line.\n\nSecond paragraph. This time\nwith multiple lines.
+ Metadata Example list - first item\n- second item\n-third
+
+.. note:: As explained in the Paragraphs_ section below, the single newline in
+ `Second paragraph, this time\nwith multiple lines.` does not actually
+ affect how that paragraph is rendered. Newlines are needed when
+ constructing lists_, though.
Adding newlines manually to a long documentation takes some effort and extra
characters also make the documentation harder to read. This can be avoided,
@@ -46,12 +51,12 @@ means that the above example could be written also as follows.
Documentation
... First line.
...
- ... Second paragraph, this time
+ ... Second paragraph. This time
... with multiple lines.
- Metadata
- ... Example
- ... Value
- ... in two lines
+ Metadata Example list
+ ... - first item
+ ... - second item
+ ... - third
No automatic newline is added if a line already ends with a literal newline
or if it ends with an `escaping backslash`__. If documentation or metadata
