From 7dc5e41224361e4006c325b78f7274a2128c3588 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Mon, 17 Jul 2023 13:24:12 +0100 Subject: [PATCH] doc: explain whitespace in env vars (#5629) --- cylc/flow/cfgspec/workflow.py | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/cylc/flow/cfgspec/workflow.py b/cylc/flow/cfgspec/workflow.py index c78fd65f574..7ef99814af2 100644 --- a/cylc/flow/cfgspec/workflow.py +++ b/cylc/flow/cfgspec/workflow.py @@ -1594,7 +1594,7 @@ def get_script_common_text(this: str, example: Optional[str] = None): You can also specify job environment templates here for :ref:`parameterized tasks `. '''): - Conf('', VDR.V_STRING, desc=''' + Conf('', VDR.V_STRING, desc=r''' A custom user defined variable for a task execution environment. @@ -1635,6 +1635,32 @@ def get_script_common_text(this: str, example: Optional[str] = None): MYITEM = %(item)s MYFILE = /path/to/%(i)03d/%(item)s + .. note:: + + As with other Cylc configurations, leading or trailing + whitespace will be stripped, so the following two + examples are equivalent: + + .. list-table:: + :class: grid-table + + * - .. code-block:: cylc + + [environment] + FOO = " a " + BAR = """ + $(foo bar baz) + """ + - .. code-block:: cylc + + [environment] + FOO = "a" + BAR = "$(foo bar baz)" + + If leading or trailing whitespace is required, consider + using the ``\0`` escape character, or set the variable + in :cylc:conf:`[..][..]env-script`. + .. versionchanged:: 7.8.7/7.9.2 Parameter environment templates (previously in