Enhance documentation of splitting long variables in Variables.

pekkaklarck · pekkaklarck · commit b0cd5510e975 · 2021-03-04T00:23:18.000+02:00
Fixes robotframework#3870.
diff --git a/doc/userguide/src/CreatingTestData/TestDataSyntax.rst b/doc/userguide/src/CreatingTestData/TestDataSyntax.rst
@@ -486,6 +486,12 @@ as well `suite metadata`__. With them split values are automatically
 `joined together with the newline character`__ to ease creating multiline
 values.
 
+The `...` syntax allows also splitting variables in the `Variable section`_.
+When long scalar variables (e.g. `${STRING}`) are split to multiple rows,
+the final value is got by concatenating the rows together. The separator is
+a space by default, but that can be changed by starting the value with
+`SEPARATOR=<sep>`.
+
 Splitting lines is illustrated in the following two examples containing
 exactly same data without and with splitting.
 
@@ -502,15 +508,17 @@ __ `Newlines in test data`_
    Default Tags       default tag 1    default tag 2    default tag 3    default tag 4    default tag 5
 
    *** Variable ***
+   ${STRING}          This is a long string. It has multiple sentences. It does not have newlines.
+   ${MULTILINE}       This is a long multiline string.\nThis is the second line.\nThis is the third and the last line.
    @{LIST}            this     list     is    quite    long     and    items in it can also be long
+   &{DICT}            first=This value is pretty long.    second=This value is even longer. It has two sentences.
 
    *** Test Cases ***
    Example
        [Tags]    you    probably    do    not    have    this    many    tags    in    real    life
        Do X    first argument    second argument    third argument    fourth argument    fifth argument    sixth argument
        ${var} =    Get X    first argument passed to this keyword is pretty long    second argument passed to this keyword is long too
 
-
 .. sourcecode:: robotframework
 
    *** Settings ***
@@ -522,8 +530,17 @@ __ `Newlines in test data`_
    ...                default tag 4    default tag 5
 
    *** Variable ***
+   ${STRING}          This is a long string.
+   ...                It has multiple sentences.
+   ...                It does not have newlines.
+   ${MULTILINE}       SEPARATOR=\n
+   ...                This is a long multiline string.
+   ...                This is the second line.
+   ...                This is the third and the last line.
    @{LIST}            this     list     is      quite    long     and
    ...                items in it can also be long
+   &{DICT}            first=This value is pretty long.
+   ...                second=This value is even longer. It has two sentences.
 
    *** Test Cases ***
    Example
diff --git a/doc/userguide/src/CreatingTestData/Variables.rst b/doc/userguide/src/CreatingTestData/Variables.rst
@@ -510,16 +510,19 @@ variables slightly more explicit.
    ${NAME} =       Robot Framework
    ${VERSION} =    2.0
 
-If a scalar variable has a long value, it can be split to multiple columns and
-rows__. By default cells are catenated together using a space, but this
-can be changed by having `SEPARATOR=<sep>` in the first cell.
+If a scalar variable has a long value, it can be `split into multiple rows`__
+by using the `...` syntax. By default rows are concatenated together using
+a space, but this can be changed by having `SEPARATOR=<sep>` as the first item.
 
 .. sourcecode:: robotframework
 
    *** Variables ***
-   ${EXAMPLE}      This value is joined    together with a space
-   ${MULTILINE}    SEPARATOR=\n    First line
-   ...             Second line     Third line
+   ${EXAMPLE}      This value is joined
+   ...             together with a space.
+   ${MULTILINE}    SEPARATOR=\n
+   ...             First line.
+   ...             Second line.
+   ...             Third line.
 
 __ `Dividing data to several rows`_
 
