[systemd-devel] [PATCH] Documentation: Clarify env var handling

[Barry Scott]

For ExecStart= provide more details on env var substitution
and how that turns into arguments.

For EnvironmentFile= explain that double quotes can be used
to protect whitespace.

Signed-off-by: Barry Scott <barry.scott at onelan.co.uk>
---

I think the docs could be improved with the extra
details you provided in you email replay to me about
arguments and the env var handling.

 man/systemd.exec.xml    |    5 +++++
 man/systemd.service.xml |   23 ++++++++++++-----------
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index b9a37da..7691e00 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -279,6 +279,11 @@
                                 assignments. Empty lines and lines
                                 starting with ; or # will be ignored,
                                 which may be used for commenting. The
+                                parser for will strip leading and
+                                trailing whitespace from the values
+                                of assignments, unless you use
+                                double quotes (").
+                                The
                                 argument passed should be an absolute
                                 file name, optionally prefixed with
                                 "-", which indicates that if the file
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 4f11020..7e3679d 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -311,18 +311,19 @@
                                 main process of the daemon. The
                                 command line accepts % specifiers as
                                 described in
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. On
-                                top of that basic environment variable
-                                substitution is supported, where
-                                <literal>${FOO}</literal> is replaced
-                                by the string value of the environment
-                                variable of the same name. Also
-                                <literal>$FOO</literal> may appear as
-                                separate word on the command line in
-                                which case the variable is replaced by
-                                its value split at whitespaces. Note
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+                                <para>On top of that basic environment variable
+                                substitution is supported. Use <literal>${FOO}</literal>
+                                as part of a word, or as word of its own on the
+                                command line, in which case it will be replaced
+                                by the value of the env var including all
+                                whitespace it contains, resulting in 1 argument.
+                                Use <literal>$FOO</literal> as a separate word
+                                on the command line, in which case it will be
+                                replaced by the value of the env var split up at
+                                whitespace, resulting in 0 or more arguments. Note
                                 that the first argument (i.e. the
-                                binary to execute) may not be a
+                                program to execute) may not be a
                                 variable, and must be a literal and
                                 absolute path name.</para></listitem>
                         </varlistentry>
-- 
1.7.5.4