man: add more details for IMPORT, PROGRAM and RUN keys

967de8face added a note that I found very hard
to understand. Reword it, and also describe how IMPORT and PROGRAM are different
from RUN.

Minor markup adjustements too.

man/udev.xml

@@ -280,13 +280,17 @@
         <varlistentry>
           <term><varname>PROGRAM</varname></term>
           <listitem>
-            <para>Execute a program to determine whether there
+            <para>Execute a program to determine whether there is a match; the key is true if the program
-            is a match; the key is true if the program returns
+            returns successfully. The device properties are made available to the executed program in the
-            successfully. The device properties are made available to the
+            environment. The program's standard output is available in the <varname>RESULT</varname>
-            executed program in the environment. The program's standard output
+            key.</para>
-            is available in the <varname>RESULT</varname> key.</para>
+
-            <para>This can only be used for very short-running foreground tasks. For details,
+            <para>This can only be used for very short-running foreground tasks. For details, see
-            see <varname>RUN</varname>.</para>
+            <varname>RUN</varname>.</para>
+
+            <para>Note that multiple <varname>PROGRAM</varname> keys may be specified in one rule, and
+            <literal>=</literal>, <literal>:=</literal>, and <literal>+=</literal> have the same effect as
+            <literal>==</literal>.</para>
           </listitem>
         </varlistentry>
 
@@ -429,9 +433,14 @@
         <varlistentry>
           <term><varname>RUN{<replaceable>type</replaceable>}</varname></term>
           <listitem>
-            <para>Add a program to the list of programs to be executed after
+            <para>Specify a program to be executed after processing of all the rules for the event. With
-            processing all the rules for a specific event, depending on
+            <literal>+=</literal>, this invocation is added to the list, and with <literal>=</literal> or
-            <literal>type</literal>:</para>
+            <literal>:=</literal>, it replaces any previous contents of the list. Please note that both
+            <literal>program</literal> and <literal>builtin</literal> types described below use a single
+            list, so clearing the list with <literal>:=</literal> and <literal>=</literal> affects both
+            types.</para>
+
+            <para><replaceable>type</replaceable> may be:</para>
             <variablelist>
               <varlistentry>
                 <term><literal>program</literal></term>
@@ -452,21 +461,21 @@
                 </listitem>
               </varlistentry>
             </variablelist>
-            <para>The program name and following arguments are separated by spaces.
+
-            Single quotes can be used to specify arguments with spaces.</para>
+            <para>The program name and following arguments are separated by spaces. Single quotes can be
-            <para>This can only be used for very short-running foreground tasks. Running an
+            used to specify arguments with spaces.</para>
-            event process for a long period of time may block all further events for
+
-            this or a dependent device.</para>
+            <para>This can only be used for very short-running foreground tasks. Running an event process for
-            <para>Starting daemons or other long-running processes is not appropriate
+            a long period of time may block all further events for this or a dependent device.</para>
-            for udev; the forked processes, detached or not, will be unconditionally
+
-            killed after the event handling has finished.</para>
+            <para>Note that running programs that access the network or mount/unmount filesystems is not
-            <para>Note that running programs that access the network or mount/unmount
+            allowed inside of udev rules, due to the default sandbox that is enforced on
-            filesystems is not allowed inside of udev rules, due to the default sandbox
+            <filename>systemd-udevd.service</filename>.</para>
-            that is enforced on <filename>systemd-udevd.service</filename>.</para>
+
-            <para>Please also note that <literal>:=</literal> and <literal>=</literal> are clearing
+            <para>Starting daemons or other long-running processes is not allowed; the forked processes,
-            both, program and builtin commands.</para>
+            detached or not, will be unconditionally killed after the event handling has finished. In order
-            <para>In order to activate long-running processes from udev rules, provide a service unit, and
+            to activate long-running processes from udev rules, provide a service unit and pull it in from a
-            pull it in from a udev device using the <varname>SYSTEMD_WANTS</varname> device property. See
+            udev device using the <varname>SYSTEMD_WANTS</varname> device property. See
             <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
             for details.</para>
           </listitem>
@@ -489,8 +498,9 @@
         <varlistentry>
           <term><varname>IMPORT{<replaceable>type</replaceable>}</varname></term>
           <listitem>
-            <para>Import a set of variables as device properties,
+            <para>Import a set of variables as device properties, depending on
-            depending on <literal>type</literal>:</para>
+            <replaceable>type</replaceable>:</para>
+
             <variablelist>
               <varlistentry>
                 <term><literal>program</literal></term>
@@ -542,8 +552,14 @@
                 </listitem>
               </varlistentry>
             </variablelist>
-            <para>This can only be used for very short-running foreground tasks. For details
+
-            see <option>RUN</option>.</para>
+            <para>This can only be used for very short-running foreground tasks. For details see
+            <option>RUN</option>.</para>
+
+            <para>Note that multiple <varname>IMPORT{}</varname> keys may be specified in one rule, and
+            <literal>=</literal>, <literal>:=</literal>, and <literal>+=</literal> have the same effect as
+            <literal>==</literal>. The key is true if the import is successful, unless <literal>!=</literal>
+            is used as the operator which causes the key to be true if the import failed.</para>
           </listitem>
         </varlistentry>
 
@@ -633,9 +649,8 @@
         <varlistentry>
           <term><option>$number</option>, <option>%n</option></term>
           <listitem>
-            <para>The kernel number for this device. For example,
+            <para>The kernel number for this device. For example, <literal>sda3</literal> has kernel number
-              <literal>sda3</literal> has kernel number <literal>3</literal>.
+            3.</para>
-            </para>
           </listitem>
         </varlistentry>