New upstream version 1.16.0 upstream/1.16.0

1 files changed, 119 insertions, 117 deletions

diff --git a/man/nmcli.xml b/man/nmcli.xml
index 2a0765d0..3f123a57 100644
--- a/man/nmcli.xml
+++ b/man/nmcli.xml
@@ -68,7 +68,9 @@
     replacement for <command>nm-applet</command> or other graphical clients.
     <command>nmcli</command> is used to create, display, edit, delete, activate,
     and deactivate network connections, as well as control and display network
-    device status.</para>
+    device status. See
+    <link linkend='nmcli-examples'><citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>7</manvolnum></citerefentry></link>
+    for ready to run nmcli examples.</para>
 
     <para>Typical uses include:</para>
     <itemizedlist>
@@ -95,98 +97,73 @@
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-t</option></arg>
-          <arg choice='plain'><option>--terse</option></arg>
+          <arg choice='plain'><option>-a</option></arg>
+          <arg choice='plain'><option>--ask</option></arg>
         </group></term>
 
         <listitem>
-          <para>Output is terse. This mode is designed and suitable for computer (script)
-          processing.</para>
+          <para>When using this option <command>nmcli</command> will stop and ask for any
+          missing required arguments, so do not use this option for non-interactive
+          purposes like scripts. This option controls, for example, whether you will be
+          prompted for a password if it is required for connecting to a network.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-p</option></arg>
-          <arg choice='plain'><option>--pretty</option></arg>
+          <arg choice='plain'><option>-c</option></arg>
+          <arg choice='plain'><option>--colors</option></arg>
+          <group choice='req'>
+            <arg choice='plain'>yes</arg>
+            <arg choice='plain'>no</arg>
+            <arg choice='plain'>auto</arg>
+          </group>
         </group></term>
 
         <listitem>
-          <para>Output is pretty. This causes <command>nmcli</command> to produce easily
-          readable outputs for humans, i.e. values are aligned, headers are printed,
-          etc.</para>
+          <para>This option controls color output (using terminal escape sequences).
+          <literal>yes</literal> enables colors, <literal>no</literal> disables them,
+          <literal>auto</literal> only produces colors when standard output is directed
+          to a terminal. The default value is <literal>auto</literal>.</para>
+          <para>The actual colors used are configured as described in
+          <citerefentry><refentrytitle>terminal-colors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          Please refer to the <link linkend='colors' endterm='colors.title' /> section for a
+          list of color names supported by <command>nmcli</command>.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-m</option></arg>
-          <arg choice='plain'><option>--mode</option></arg>
-          <group choice='req'>
-            <arg choice='plain'>tabular</arg>
-            <arg choice='plain'>multiline</arg>
-          </group>
+          <arg choice='plain'><option>--complete-args</option></arg>
         </group></term>
 
         <listitem>
-          <para>Switch between tabular and multiline output:</para>
-
-          <variablelist>
-            <varlistentry>
-              <term><arg choice='plain'>tabular</arg></term>
-              <listitem>
-                <para>Output is a table where each line describes a single entry.
-                Columns define particular properties of the entry.</para>
-              </listitem>
-            </varlistentry>
-
-            <varlistentry>
-              <term><arg choice='plain'>multiline</arg></term>
-              <listitem>
-                <para>Each entry comprises multiple lines, each property on its
-                own line. The values are prefixed with the property name.</para>
-              </listitem>
-            </varlistentry>
-          </variablelist>
-
-          <para>If omitted, default is <literal>tabular</literal> for most commands.
-          For the commands producing more structured information, that cannot be
-          displayed on a single line, default is <literal>multiline</literal>.
-          Currently, they are:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><literal>nmcli connection show <replaceable>ID</replaceable></literal></para>
-            </listitem>
+          <para>Instead of conducting the desired action, <command>nmcli</command>
+          will list possible completions for the last argument. This is useful to implement
+          argument completion in shell.</para>
 
-            <listitem>
-              <para><literal>nmcli device show</literal></para>
-            </listitem>
-          </itemizedlist>
+          <para>The <link linkend='exit_status'>exit status</link> will indicate success
+          or return a code 65 to indicate the last argument is a file name.</para>
 
+          <para>NetworkManager ships with command completion support for GNU Bash.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-c</option></arg>
-          <arg choice='plain'><option>--colors</option></arg>
+          <arg choice='plain'><option>-e</option></arg>
+          <arg choice='plain'><option>--escape</option></arg>
           <group choice='req'>
             <arg choice='plain'>yes</arg>
             <arg choice='plain'>no</arg>
-            <arg choice='plain'>auto</arg>
           </group>
         </group></term>
 
         <listitem>
-          <para>This option controls color output (using terminal escape sequences).
-          <literal>yes</literal> enables colors, <literal>no</literal> disables them,
-          <literal>auto</literal> only produces colors when standard output is directed
-          to a terminal. The default value is <literal>auto</literal>.</para>
-          <para>The actual colors used are configured as described in
-          <citerefentry><refentrytitle>terminal-colors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-          Please refer to the <link linkend='colors' endterm='colors.title' /> section for a
-          list of color names supported by <command>nmcli</command>.</para>
+          <para>Whether to escape <literal>:</literal> and <literal>\</literal> characters in terse tabular mode. The
+          escape character is <literal>\</literal>.</para>
+
+          <para>If omitted, default is <literal>yes</literal>.</para>
         </listitem>
       </varlistentry>
 
@@ -238,33 +215,74 @@
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-e</option></arg>
-          <arg choice='plain'><option>--escape</option></arg>
+          <arg choice='plain'><option>-h</option></arg>
+          <arg choice='plain'><option>--help</option></arg>
+        </group></term>
+
+        <listitem>
+          <para>Print help information.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><group choice='plain'>
+          <arg choice='plain'><option>-m</option></arg>
+          <arg choice='plain'><option>--mode</option></arg>
           <group choice='req'>
-            <arg choice='plain'>yes</arg>
-            <arg choice='plain'>no</arg>
+            <arg choice='plain'>tabular</arg>
+            <arg choice='plain'>multiline</arg>
           </group>
         </group></term>
 
         <listitem>
-          <para>Whether to escape <literal>:</literal> and <literal>\</literal> characters in terse tabular mode. The
-          escape character is <literal>\</literal>.</para>
+          <para>Switch between tabular and multiline output:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term><arg choice='plain'>tabular</arg></term>
+              <listitem>
+                <para>Output is a table where each line describes a single entry.
+                Columns define particular properties of the entry.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><arg choice='plain'>multiline</arg></term>
+              <listitem>
+                <para>Each entry comprises multiple lines, each property on its
+                own line. The values are prefixed with the property name.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
+          <para>If omitted, default is <literal>tabular</literal> for most commands.
+          For the commands producing more structured information, that cannot be
+          displayed on a single line, default is <literal>multiline</literal>.
+          Currently, they are:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>nmcli connection show <replaceable>ID</replaceable></literal></para>
+            </listitem>
+
+            <listitem>
+              <para><literal>nmcli device show</literal></para>
+            </listitem>
+          </itemizedlist>
 
-          <para>If omitted, default is <literal>yes</literal>.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-a</option></arg>
-          <arg choice='plain'><option>--ask</option></arg>
+          <arg choice='plain'><option>-p</option></arg>
+          <arg choice='plain'><option>--pretty</option></arg>
         </group></term>
 
         <listitem>
-          <para>When using this option <command>nmcli</command> will stop and ask for any
-          missing required arguments, so do not use this option for non-interactive
-          purposes like scripts. This option controls, for example, whether you will be
-          prompted for a password if it is required for connecting to a network.</para>
+          <para>Output is pretty. This causes <command>nmcli</command> to produce easily
+          readable outputs for humans, i.e. values are aligned, headers are printed,
+          etc.</para>
         </listitem>
       </varlistentry>
 
@@ -283,37 +301,13 @@
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-w</option></arg>
-          <arg choice='plain'><option>--wait</option></arg></group>
-          <arg choice='plain'><replaceable>seconds</replaceable></arg>
-        </term>
-
-        <listitem>
-          <para>This option sets a timeout period for which <command>nmcli</command> will
-          wait for NetworkManager to finish operations. It is
-          especially useful for commands that may take a longer time to complete, e.g.
-          connection activation.</para>
-
-          <para>Specifying a value of <literal>0</literal> instructs
-          <command>nmcli</command> not to wait but to exit immediately with a status of
-          success. The default value depends on the executed command.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><group choice='plain'>
-          <arg choice='plain'><option>--complete-args</option></arg>
+          <arg choice='plain'><option>-t</option></arg>
+          <arg choice='plain'><option>--terse</option></arg>
         </group></term>
 
         <listitem>
-          <para>Instead of conducting the desired action, <command>nmcli</command>
-          will list possible completions for the last argument. This is useful to implement
-          argument completion in shell.</para>
-
-          <para>The <link linkend='exit_status'>exit status</link> will indicate success
-          or return a code 65 to indicate the last argument is a file name.</para>
-
-          <para>NetworkManager ships with command completion support for GNU Bash.</para>
+          <para>Output is terse. This mode is designed and suitable for computer (script)
+          processing.</para>
         </listitem>
       </varlistentry>
 
@@ -330,12 +324,20 @@
 
       <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-h</option></arg>
-          <arg choice='plain'><option>--help</option></arg>
-        </group></term>
+          <arg choice='plain'><option>-w</option></arg>
+          <arg choice='plain'><option>--wait</option></arg></group>
+          <arg choice='plain'><replaceable>seconds</replaceable></arg>
+        </term>
 
         <listitem>
-          <para>Print help information.</para>
+          <para>This option sets a timeout period for which <command>nmcli</command> will
+          wait for NetworkManager to finish operations. It is
+          especially useful for commands that may take a longer time to complete, e.g.
+          connection activation.</para>
+
+          <para>Specifying a value of <literal>0</literal> instructs
+          <command>nmcli</command> not to wait but to exit immediately with a status of
+          success. The default value depends on the executed command.</para>
         </listitem>
       </varlistentry>
 
@@ -831,9 +833,10 @@
           <para>Be aware that this command deactivates the specified active connection,
           but the device on which the connection was active, is still ready to connect
           and will perform auto-activation by looking for a suitable connection that has
-          the 'autoconnect' flag set. This includes the just deactivated connection. So
-          if the connection is set to auto-connect, it will be automatically started on
-          the disconnected device again.</para>
+          the 'autoconnect' flag set. Note that the deactivating connection profile is
+          internally blocked from autoconnecting again. Hence it will not autoconnect
+          until reboot or until the user performs an action that unblocks autoconnect,
+          like modifying the profile or explicitly activating it.</para>
 
           <para>In most cases you may want to use <command>device disconnect</command>
           command instead.</para>
@@ -1442,14 +1445,13 @@
 
         <listitem>
           <para>Connect to a Wi-Fi network specified by SSID or BSSID. The command
-          creates a new connection and then activates it on a device. This is a
-          command-line counterpart of clicking an SSID in a GUI client. The command
-          always creates a new connection and thus it is mainly useful for connecting to
-          new Wi-Fi networks. If a connection for the network already exists, it is
-          better to bring up (activate) the existing connection as follows:
+          finds a matching connection or creates one and then activates it on a device.
+          This is a command-line counterpart of clicking an SSID in a GUI client. If
+          a connection for the network already exists, it is possible to bring up
+          (activate) the existing profile as follows:
           <command>nmcli con up id <replaceable>name</replaceable></command>. Note that
-          only open, WEP and WPA-PSK networks are supported at the moment. It is also
-          supposed that IP configuration is obtained via DHCP.</para>
+          only open, WEP and WPA-PSK networks are supported if no previous connection
+          exists. It is also assumed that IP configuration is obtained via DHCP.</para>
 
           <para>If <option>--wait</option> option is not specified, the default timeout will be 90
           seconds.</para>
@@ -2537,9 +2539,9 @@ It's equivalent to the <literal>+bond.options 'option=value'</literal> syntax.</
       </varlistentry>
 
       <varlistentry>
-        <term><userinput>nmcli --show-secrets connection show "My Home WiFi"</userinput></term>
+        <term><userinput>nmcli --show-secrets connection show "My Home Wi-Fi"</userinput></term>
         <listitem>
-          <para>shows details for "My Home WiFi" connection profile with all passwords.
+          <para>shows details for "My Home Wi-Fi" connection profile with all passwords.
           Without <option>--show-secrets</option> option, secrets would not be
           displayed.</para>
         </listitem>