man: extend documentation on the unit name escaping logic

poettering · poettering · commit 2651d037518b · 2017-11-10T19:45:29.000+01:00
diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml
@@ -73,6 +73,9 @@
     special mode of escaping is applied instead, which assumes the
     string is already escaped but will escape everything that
     appears obviously non-escaped.</para>
+
+    <para>For details on the escaping and unescaping algorithms see the relevant section in
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
   </refsect1>
 
   <refsect1>
@@ -107,11 +110,12 @@
         <term><option>--path</option></term>
         <term><option>-p</option></term>
 
-        <listitem><para>When escaping or unescaping a string, assume
-        it refers to a file system path. This eliminates leading,
-        trailing or duplicate <literal>/</literal> characters
-        and rejects <literal>.</literal> and <literal>..</literal>
-        path components.</para></listitem>
+        <listitem><para>When escaping or unescaping a string, assume it refers to a file system path. This eliminates
+        leading, trailing or duplicate <literal>/</literal> characters and rejects <literal>.</literal> and
+        <literal>..</literal> path components. This is particularly useful for generating strings suitable for
+        unescaping with the <literal>%f</literal> specifier in unit files, see
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -172,6 +176,7 @@ systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service sy
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
@@ -213,22 +213,6 @@
     socket-based activation which make dependencies implicit,
     resulting in a both simpler and more flexible system.</para>
 
-    <para>Some unit names reflect paths existing in the file system
-    namespace. Example: a device unit
-    <filename>dev-sda.device</filename> refers to a device with the
-    device node <filename noindex='true'>/dev/sda</filename> in the
-    file system namespace. If this applies, a special way to escape
-    the path name is used, so that the result is usable as part of a
-    filename. Basically, given a path, "/" is replaced by "-", and all
-    other characters which are not ASCII alphanumerics are replaced by
-    C-style "\x2d" escapes (except that "_" is never replaced and "."
-    is only replaced when it would be the first character in the
-    escaped path). The root directory "/" is encoded as single dash,
-    while otherwise the initial and ending "/" are removed from all
-    paths during transformation. This escaping is reversible. Properly
-    escaped paths can be generated using the
-    <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    command.</para>
 
     <para>Optionally, units may be instantiated from a
     template file at runtime. This allows creation of
@@ -265,6 +249,32 @@
 
   </refsect1>
 
+  <refsect1>
+    <title>String Escaping for Inclusion in Unit Names</title>
+
+    <para>Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string
+    escaping is used, in order to map strings containing arbitrary byte values (except NUL) into valid unit names and
+    their restricted character set. A common special case are unit names that reflect paths to objects in the file
+    system hierarchy. Example: a device unit <filename>dev-sda.device</filename> refers to a device with the device
+    node <filename noindex='true'>/dev/sda</filename> in the file system.</para>
+
+    <para>The escaping algorithm operates as follows: given a string, any <literal>/</literal> character is replaced by
+    <literal>-</literal>, and all other characters which are not ASCII alphanumerics or <literal>_</literal> are
+    replaced by C-style <literal>\x2d</literal> escapes. In addition, <literal>.</literal> is replaced with such a
+    C-style escape when it would appear as the first character in the escaped string.</para>
+
+    <para>When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the
+    root directory <literal>/</literal> is encoded as single dash <literal>-</literal>. In addition, any leading,
+    trailing or duplicate <literal>/</literal> characters are removed from the string before transformation. Example:
+    <filename>/foo//bar/baz/</filename> becomes <literal>foo-bar-baz</literal>.</para>
+
+    <para>This escaping is fully reversible, as long as it is known whether the escaped string was a path (the
+    unescaping results are different for paths and non-path strings). The
+    <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> command may be
+    used to apply and reverse escaping on arbitrary strings. Use <command>systemd-escape --path</command> to escape
+    path strings, and <command>systemd-escape</command> without <option>--path</option> otherwise.</para>
+  </refsect1>
+
   <refsect1>
     <title>Implicit Dependencies</title>
 
@@ -1241,7 +1251,7 @@
           <row>
       <entry><literal>%N</literal></entry>
       <entry>Unescaped full unit name</entry>
-      <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
+      <entry>Same as <literal>%n</literal>, but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above). </entry>
           </row>
           <row>
       <entry><literal>%p</literal></entry>
@@ -1266,7 +1276,7 @@
           <row>
       <entry><literal>%f</literal></entry>
       <entry>Unescaped filename</entry>
-      <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>.</entry>
+      <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry>
           </row>
           <row>
       <entry><literal>%t</literal></entry>
