UG: Clarify \n in documentation paragraphs. Fixes robotframework#3021.

pekkaklarck · pekkaklarck · commit ec781c61ca30 · 2018-12-03T23:31:44.000+02:00
diff --git a/doc/userguide/src/Appendices/DocumentationFormatting.rst b/doc/userguide/src/Appendices/DocumentationFormatting.rst
@@ -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
