man: merge branch 'bg/man'

Some small improvements to man pages and program help

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/merge_requests/41

5 files changed, 153 insertions, 141 deletions

diff --git a/clients/cli/devices.c b/clients/cli/devices.c
index 88fbae33f3..8e26a14450 100644
--- a/clients/cli/devices.c
+++ b/clients/cli/devices.c
@@ -703,7 +703,7 @@ usage (void)
 	              "  disconnect <ifname> ...\n\n"
 	              "  delete <ifname> ...\n\n"
 	              "  monitor <ifname> ...\n\n"
-	              "  wifi [list [ifname <ifname>] [bssid <BSSID>]]\n\n"
+	              "  wifi [list [ifname <ifname>] [bssid <BSSID>] [--rescan yes|no|auto]]\n\n"
 	              "  wifi connect <(B)SSID> [password <password>] [wep-key-type key|phrase] [ifname <ifname>]\n"
 	              "                         [bssid <BSSID>] [name <name>] [private yes|no] [hidden yes|no]\n\n"
 	              "  wifi hotspot [ifname <ifname>] [con-name <name>] [ssid <SSID>] [band a|bg] [channel <channel>] [password <password>]\n\n"
@@ -838,10 +838,11 @@ usage_device_wifi (void)
 	              "\n"
 	              "Perform operation on Wi-Fi devices.\n"
 	              "\n"
-	              "ARGUMENTS := [list [ifname <ifname>] [bssid <BSSID>]]\n"
+	              "ARGUMENTS := [list [ifname <ifname>] [bssid <BSSID>] [--rescan yes|no|auto]]\n"
 	              "\n"
 	              "List available Wi-Fi access points. The 'ifname' and 'bssid' options can be\n"
-	              "used to list APs for a particular interface, or with a specific BSSID.\n"
+	              "used to list APs for a particular interface, or with a specific BSSID. The"
+	              "--rescan flags tells whether a new wifi scan should be triggered.\n"
 	              "\n"
 	              "ARGUMENTS := connect <(B)SSID> [password <password>] [wep-key-type key|phrase] [ifname <ifname>]\n"
 	              "                     [bssid <BSSID>] [name <name>] [private yes|no] [hidden yes|no]\n"
diff --git a/clients/cli/nmcli.c b/clients/cli/nmcli.c
index df152c1f87..7e8477ccd8 100644
--- a/clients/cli/nmcli.c
+++ b/clients/cli/nmcli.c
@@ -245,19 +245,19 @@ usage (void)
 	g_printerr (_("Usage: nmcli [OPTIONS] OBJECT { COMMAND | help }\n"
 	              "\n"
 	              "OPTIONS\n"
-	              "  -o[verview]                                    overview mode (hide default values)\n"
-	              "  -t[erse]                                       terse output\n"
-	              "  -p[retty]                                      pretty output\n"
-	              "  -m[ode] tabular|multiline                      output mode\n"
-	              "  -c[olors] auto|yes|no                          whether to use colors in output\n"
-	              "  -f[ields] <field1,field2,...>|all|common       specify fields to output\n"
-	              "  -g[et-values] <field1,field2,...>|all|common   shortcut for -m tabular -t -f\n"
-	              "  -e[scape] yes|no                               escape columns separators in values\n"
-	              "  -a[sk]                                         ask for missing parameters\n"
-	              "  -s[how-secrets]                                allow displaying passwords\n"
-	              "  -w[ait] <seconds>                              set timeout waiting for finishing operations\n"
-	              "  -v[ersion]                                     show program version\n"
-	              "  -h[elp]                                        print this help\n"
+	              "  -a, --ask                                ask for missing parameters\n"
+	              "  -c, --colors auto|yes|no                 whether to use colors in output\n"
+	              "  -e, --escape yes|no                      escape columns separators in values\n"
+	              "  -f, --fields <field,...>|all|common      specify fields to output\n"
+	              "  -g, --get-values <field,...>|all|common  shortcut for -m tabular -t -f\n"
+	              "  -h, --help                               print this help\n"
+	              "  -m, --mode tabular|multiline             output mode\n"
+	              "  -o, --overview                           overview mode\n"
+	              "  -p, --pretty                             pretty output\n"
+	              "  -s, --show-secrets                       allow displaying passwords\n"
+	              "  -t, --terse                              terse output\n"
+	              "  -v, --version                            how program version\n"
+	              "  -w, --wait <seconds>                     set timeout waiting for finishing operations\n"
 	              "\n"
 	              "OBJECT\n"
 	              "  g[eneral]       NetworkManager's general status and operations\n"
diff --git a/clients/nm-online.c b/clients/nm-online.c
index 38ce03c8f8..18ca713b3d 100644
--- a/clients/nm-online.c
+++ b/clients/nm-online.c
@@ -249,10 +249,10 @@ main (int argc, char *argv[])
 	GOptionContext *opt_ctx = NULL;
 	gboolean success;
 	GOptionEntry options[] = {
-		{"timeout", 't', 0, G_OPTION_ARG_INT, &t_secs, N_("Time to wait for a connection, in seconds (without the option, default value is 30)"), "<timeout>"},
-		{"exit", 'x', 0, G_OPTION_ARG_NONE, &data.exit_no_nm, N_("Exit immediately if NetworkManager is not running or connecting"), NULL},
 		{"quiet", 'q', 0, G_OPTION_ARG_NONE, &data.quiet, N_("Don't print anything"), NULL},
 		{"wait-for-startup", 's', 0, G_OPTION_ARG_NONE, &data.wait_startup, N_("Wait for NetworkManager startup instead of a connection"), NULL},
+		{"timeout", 't', 0, G_OPTION_ARG_INT, &t_secs, N_("Time to wait for a connection, in seconds (without the option, default value is 30)"), "<timeout>"},
+		{"exit", 'x', 0, G_OPTION_ARG_NONE, &data.exit_no_nm, N_("Exit immediately if NetworkManager is not running or connecting"), NULL},
 		{ NULL },
 	};
 
diff --git a/man/nm-online.xml b/man/nm-online.xml
index 297920dd6f..d40aef98c9 100644
--- a/man/nm-online.xml
+++ b/man/nm-online.xml
@@ -68,29 +68,13 @@
   <refsect1 id='options'><title>Options</title>
     <variablelist>
       <varlistentry>
-        <term>
-          <group choice='plain'>
-            <arg choice='plain'><option>-t</option></arg>
-            <arg choice='plain'><option>--timeout</option></arg>
-          </group>
-          <arg choice='plain'><replaceable>seconds</replaceable></arg>
-        </term>
-
-        <listitem>
-          <para>Time to wait for a connection, in seconds. If the option is not provided,
-          the default timeout is 30 seconds.</para>
-        </listitem>
-      </varlistentry>
-
-
-      <varlistentry>
         <term><group choice='plain'>
-          <arg choice='plain'><option>-x</option></arg>
-          <arg choice='plain'><option>--exit</option></arg>
+          <arg choice='plain'><option>-h</option></arg>
+          <arg choice='plain'><option>--help</option></arg>
         </group></term>
 
         <listitem>
-          <para>Exit immediately if NetworkManager is not running or connecting.</para>
+          <para>Print help information.</para>
         </listitem>
       </varlistentry>
 
@@ -122,6 +106,33 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term>
+          <group choice='plain'>
+            <arg choice='plain'><option>-t</option></arg>
+            <arg choice='plain'><option>--timeout</option></arg>
+          </group>
+          <arg choice='plain'><replaceable>seconds</replaceable></arg>
+        </term>
+
+        <listitem>
+          <para>Time to wait for a connection, in seconds. If the option is not provided,
+          the default timeout is 30 seconds.</para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><group choice='plain'>
+          <arg choice='plain'><option>-x</option></arg>
+          <arg choice='plain'><option>--exit</option></arg>
+        </group></term>
+
+        <listitem>
+          <para>Exit immediately if NetworkManager is not running or connecting.</para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
   </refsect1>
 
diff --git a/man/nmcli.xml b/man/nmcli.xml
index 2a0765d0ab..b98651a799 100644
--- a/man/nmcli.xml
+++ b/man/nmcli.xml
@@ -95,98 +95,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 +213,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 +299,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 +322,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>