WIP: man: explain the format for device specifier in manual page for NetworkManager.confth/spec-match-bgo743411

TODO: just a first shot. The layout is terrible. Should be fixed.
Rewording is necessary too. Fixup! commits are welcome

1 files changed, 48 insertions, 14 deletions

diff --git a/man/NetworkManager.conf.xml.in b/man/NetworkManager.conf.xml.in
index d9d51b846a..ebd90da3ea 100644
--- a/man/NetworkManager.conf.xml.in
+++ b/man/NetworkManager.conf.xml.in
@@ -162,7 +162,7 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	<filename>/var/run/NetworkManager/no-auto-default.state</filename>
 	to prevent creating the default connection for that device
 	again.</para>
-	<para>
+	<para>See <xref linkend="device-spec"/> for the supported format
 	  <programlisting>
 	    no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee
 	    no-auto-default=eth0,eth1
@@ -194,8 +194,7 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	    the device when carrier is lost.
 	  </para>
 	  <para>
-	    May have the special value <literal>*</literal> to apply
-	    to all devices.
+	    Devices are specified according to <xref linkend="device-spec"/>.
 	  </para>
 	  <para>
 	    Note that the "carrier" property of NMDevices and device D-Bus
@@ -279,17 +278,8 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	<varlistentry>
 	  <term><varname>unmanaged-devices</varname></term>
 	  <listitem><para>Set devices that should be ignored by
-	  NetworkManager when using the <literal>keyfile</literal>
-	  plugin. Devices are specified in the following
-	  format:</para>
-	  <para><literal>mac:&lt;hwaddr&gt;</literal> or
-	  <literal>interface-name:&lt;ifname&gt;</literal>.  Here
-	  <literal>hwaddr</literal> is the MAC address of the device
-	  to be ignored, in hex-digits-and-colons notation.
-	  <literal>ifname</literal> is the interface name of the
-	  ignored device.</para>
-	  <para>Multiple entries are separated with semicolons. No
-	  spaces are allowed in the value.</para>
+		NetworkManager. Devices are specified according to <xref linkend="device-spec"/>.
+	  </para>
 	  <para>
 	    Example:
 	    <programlisting>
@@ -546,6 +536,50 @@ unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth
   </refsect1>
 
   <refsect1>
+    <title>Detail</title>
+    <refsect2 id="device-spec">
+      <title>Device List Format</title>
+      <para>
+          Properties such as <literal>main.no-auto-default</literal>, <literal>main.ignore-carrier</literal>,
+          and <literal>keyfile.unmanaged-devices</literal> name a list of matching devices.
+          Devices can be specified using the following format:
+      </para>
+      <para>"<literal>*</literal>": matches every device</para>
+      <para>"<literal>IFNAME</literal>": exact match of interface name of device.
+          Globbing is not supported and the match is case sensitive</para>
+      <para>"<literal>HWADDR</literal>": exact match of the mac address of the
+          device. Globbing is not supported and the match is case insensitive</para>
+      <para>"<literal>interface-name:IFNAME</literal>": match of interface name of device.
+          Simple globbing is supported using '?' and '*' and the match is case sensitive. Escaping of
+          globbing characters is not supported.</para>
+      <para>"<literal>interface-name:=IFNAME</literal>": exact match of interface name of device.
+          Globbing is not supported and the match is case sensitive.</para>
+      <para>"<literal>mac:HWADDR</literal>": match the mac address of the device.
+          Globbing is not supported and the match is not case sensitive.</para>
+      <para>"<literal>s390-subchannels:HWADDR</literal>": match the subchannel address of the device.
+          Globbing is not supported and the match is not case sensitive.</para>
+      <para>"<literal>except:SPEC</literal>": negated match. SPEC must be explicitly qualified with
+          a prefix such as <literal>interface-name:</literal>. A matching except has higher priority.
+          </para>
+      <para>"<literal>SPEC[;,]SPEC</literal>": multiple specs can be concatenated with comma or
+          semicolon. The order of the specs does not matter as "<literal>except:SPEC</literal>" has
+          higher priority.</para>
+      <para>Backslash is supported to escape the separators ';' and ',', and to express special
+          characters such as newline ('\n'), tabulator ('\t') and backslash ('\\'). The globbing of interface names
+          cannot be escaped.</para>
+      <para>
+        Example:
+        <programlisting>
+interface-name:em4
+mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
+interface-name:vboxnet*,except:interface-name:vboxnet2
+*,except:mac:00:22:68:1c:59:b1
+        </programlisting>
+      </para>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry>,