man: Document additional environment.d syntax

man/environment.d.xml

@@ -68,13 +68,33 @@
     <literal>${<replaceable>FOO</replaceable>:+<replaceable>ALTERNATE_VALUE</replaceable>}</literal>
     to expand to <replaceable>ALTERNATE_VALUE</replaceable> as long as
     <literal>${<replaceable>FOO</replaceable>}</literal> would have expanded to a non-empty value.
+    You can escape a literal dollar sign <literal>$</literal> by doubling it, as in
+    <literal>$$</literal>.</para>
+
+    <para>A backslash character <literal>\</literal> followed by a newline acts as a line
+    continuation (both characters are discarded); in all other cases, the backslash is consumed and
+    the following character is included literally in the value. This can be used to preserve
+    leading/trailing whitespace or include literal backslashes.</para>
+
+    <para>You may optionally enclose the right hand side of assignments in pairs of either
+    <constant>'</constant>single quotes<constant>'</constant> or <constant>"</constant>double
+    quotes<constant>"</constant>; these will be stripped from the value before saving it. Using
+    either quoting style does not affect variable expansion; however, single quotes disable
+    backslash escaping entirely, while double quoting removes backslashes that precede double quotes
+    <literal>"</literal>, dollar signs <literal>$</literal>, backslashes <literal>\</literal>,
+    backticks <literal>`</literal>, and newlines, and leaves all other backslashes in place.</para>
+
+    <para>Leading and trailing whitespace characters are stripped from both the left and right hand
+    sides of the assignment. To preserve such spaces in the value, you can either enclose the entire
+    value in quotes, or escape the space characters with backslashes. You can also include literal
+    newlines in the value by enclosing it in quotes.</para>
+
+    <para>Each <replaceable>KEY</replaceable> must be a valid variable name. Empty lines and lines
+    beginning with the comment characters <literal>#</literal> or <literal>;</literal> are ignored.
     No other elements of shell syntax are supported.</para>
 
-    <para>Each <replaceable>KEY</replaceable> must be a valid variable name. Empty lines
-    and lines beginning with the comment character <literal>#</literal> are ignored.</para>
-
     <refsect2>
-      <title>Example</title>
+      <title>Examples</title>
       <example>
         <title>Setup environment to allow access to a program installed in
         <filename index="false">/opt/foo</filename></title>
@@ -82,10 +102,39 @@
         <para><filename index="false">/etc/environment.d/60-foo.conf</filename>:
         </para>
         <programlisting>
-        FOO_DEBUG=force-software-gl,log-verbose
-        PATH=/opt/foo/bin:$PATH
-        LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
-        XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/}
+FOO_DEBUG=force-software-gl,log-verbose
+PATH=/opt/foo/bin:$PATH
+LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
+XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/}
+</programlisting>
+      </example>
+
+      <example>
+        <title>Escaping and variable expansion</title>
+
+        <para><filename index="false">/etc/environment.d/70-bar.conf</filename>:
+        </para>
+        <programlisting>
+# A comment
+test_var=(variable)
+; Another comment
+test_comment=value # This is a part of the variable, and not a comment!
+
+test_none= \ before\
+after "" '' \${test_var}
+test_double=" \ before\
+after "" '' \${test_var}"
+test_single=' \ before\
+after "" '' \${test_var}'
+
+# The above example produces the following environment variables, written using
+# C-style string escapes:
+#
+# test_var="(variable)"
+# test_comment="value # This is a part of the variable, and not a comment!"
+# test_none=" beforeafter \"\" '' (variable)"
+# test_double=" \\ beforeafter  '' (variable)"
+# test_single=" \\ before\\\nafter \"\"  \\(variable)"
 </programlisting>
       </example>
     </refsect2>