From d76ac490f570ac835dd1f9e8ad54047a4910d9e7 Mon Sep 17 00:00:00 2001 From: Beniamino Galvani Date: Wed, 31 Oct 2018 13:46:07 +0100 Subject: [PATCH 1/4] cli: sort options in man page and program help Options are displayed in a random order, sort them. --- clients/cli/nmcli.c | 18 +-- man/nmcli.xml | 282 ++++++++++++++++++++++---------------------- 2 files changed, 150 insertions(+), 150 deletions(-) diff --git a/clients/cli/nmcli.c b/clients/cli/nmcli.c index df152c1f87..d28bd519fe 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" + " -a[sk] ask for missing parameters\n" " -c[olors] auto|yes|no whether to use colors in output\n" + " -e[scape] yes|no escape columns separators in values\n" " -f[ields] |all|common specify fields to output\n" " -g[et-values] |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] set timeout waiting for finishing operations\n" - " -v[ersion] show program version\n" " -h[elp] print this help\n" + " -m[ode] tabular|multiline output mode\n" + " -o[verview] overview mode (hide default values)\n" + " -p[retty] pretty output\n" + " -s[how-secrets] allow displaying passwords\n" + " -t[erse] terse output\n" + " -v[ersion] show program version\n" + " -w[ait] set timeout waiting for finishing operations\n" "\n" "OBJECT\n" " g[eneral] NetworkManager's general status and operations\n" diff --git a/man/nmcli.xml b/man/nmcli.xml index 2a0765d0ab..b98651a799 100644 --- a/man/nmcli.xml +++ b/man/nmcli.xml @@ -95,26 +95,130 @@ - - + + - Output is terse. This mode is designed and suitable for computer (script) - processing. + When using this option nmcli 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. - - + + + + yes + no + auto + - Output is pretty. This causes nmcli to produce easily - readable outputs for humans, i.e. values are aligned, headers are printed, - etc. + This option controls color output (using terminal escape sequences). + yes enables colors, no disables them, + auto only produces colors when standard output is directed + to a terminal. The default value is auto. + The actual colors used are configured as described in + terminal-colors.d5. + Please refer to the section for a + list of color names supported by nmcli. + + + + + + + + + + Instead of conducting the desired action, nmcli + will list possible completions for the last argument. This is useful to implement + argument completion in shell. + + The exit status will indicate success + or return a code 65 to indicate the last argument is a file name. + + NetworkManager ships with command completion support for GNU Bash. + + + + + + + + + yes + no + + + + + Whether to escape : and \ characters in terse tabular mode. The + escape character is \. + + If omitted, default is yes. + + + + + + + + + field1,field2 + all + common + + + + + This option is used to specify what fields (column names) should be + printed. Valid field names differ for specific commands. List available fields + by providing an invalid value to the option. + all is used to print all valid field values of the + command. common is used to print common field values of + the command. + + If omitted, default is common. + + + + + + + + + field1,field2 + all + common + + + + + This option is used to print values from specific fields. It is basically + a shortcut for --mode tabular --terse --fields and is a convenient + way to retrieve values for particular fields. The values are printed one per line + without headers. + + If a section is specified instead of a field, the section name will be printed + followed by colon separated values of the fields belonging to that section, all on + the same line. + + + + + + + + + + + Print help information. @@ -169,102 +273,14 @@ - - - - yes - no - auto - + + - This option controls color output (using terminal escape sequences). - yes enables colors, no disables them, - auto only produces colors when standard output is directed - to a terminal. The default value is auto. - The actual colors used are configured as described in - terminal-colors.d5. - Please refer to the section for a - list of color names supported by nmcli. - - - - - - - - - field1,field2 - all - common - - - - - This option is used to specify what fields (column names) should be - printed. Valid field names differ for specific commands. List available fields - by providing an invalid value to the option. - all is used to print all valid field values of the - command. common is used to print common field values of - the command. - - If omitted, default is common. - - - - - - - - - field1,field2 - all - common - - - - - This option is used to print values from specific fields. It is basically - a shortcut for --mode tabular --terse --fields and is a convenient - way to retrieve values for particular fields. The values are printed one per line - without headers. - - If a section is specified instead of a field, the section name will be printed - followed by colon separated values of the fields belonging to that section, all on - the same line. - - - - - - - - - yes - no - - - - - Whether to escape : and \ characters in terse tabular mode. The - escape character is \. - - If omitted, default is yes. - - - - - - - - - - - When using this option nmcli 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. + Output is pretty. This causes nmcli to produce easily + readable outputs for humans, i.e. values are aligned, headers are printed, + etc. @@ -281,6 +297,29 @@ + + + + + + + + Output is terse. This mode is designed and suitable for computer (script) + processing. + + + + + + + + + + + Show nmcli version. + + + @@ -300,45 +339,6 @@ - - - - - - - Instead of conducting the desired action, nmcli - will list possible completions for the last argument. This is useful to implement - argument completion in shell. - - The exit status will indicate success - or return a code 65 to indicate the last argument is a file name. - - NetworkManager ships with command completion support for GNU Bash. - - - - - - - - - - - Show nmcli version. - - - - - - - - - - - Print help information. - - - From e107d3b59339d1c5b31f8f799bd752ccdf5ea45a Mon Sep 17 00:00:00 2001 From: Beniamino Galvani Date: Wed, 31 Oct 2018 13:46:30 +0100 Subject: [PATCH 2/4] cli: display double-dash long options in help We support all of these: nmcli -v nmcli -version nmcli --version Change the help output to display the first and last versions for options, since they are the most common ones for command line tools. --- clients/cli/nmcli.c | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/clients/cli/nmcli.c b/clients/cli/nmcli.c index d28bd519fe..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" - " -a[sk] ask for missing parameters\n" - " -c[olors] auto|yes|no whether to use colors in output\n" - " -e[scape] yes|no escape columns separators in values\n" - " -f[ields] |all|common specify fields to output\n" - " -g[et-values] |all|common shortcut for -m tabular -t -f\n" - " -h[elp] print this help\n" - " -m[ode] tabular|multiline output mode\n" - " -o[verview] overview mode (hide default values)\n" - " -p[retty] pretty output\n" - " -s[how-secrets] allow displaying passwords\n" - " -t[erse] terse output\n" - " -v[ersion] show program version\n" - " -w[ait] set timeout waiting for finishing operations\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 |all|common specify fields to output\n" + " -g, --get-values |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 set timeout waiting for finishing operations\n" "\n" "OBJECT\n" " g[eneral] NetworkManager's general status and operations\n" From 15d722b70c3958a44abdb4f3fc13690f9aa59bed Mon Sep 17 00:00:00 2001 From: Beniamino Galvani Date: Wed, 31 Oct 2018 13:47:02 +0100 Subject: [PATCH 3/4] nm-online: sort options in man page and program help --- clients/nm-online.c | 4 ++-- man/nm-online.xml | 49 +++++++++++++++++++++++++++------------------ 2 files changed, 32 insertions(+), 21 deletions(-) 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)"), ""}, - {"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)"), ""}, + {"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 @@ -67,30 +67,14 @@ Options - - - - - - - seconds - - - - Time to wait for a connection, in seconds. If the option is not provided, - the default timeout is 30 seconds. - - - - - - + + - Exit immediately if NetworkManager is not running or connecting. + Print help information. @@ -122,6 +106,33 @@ + + + + + + + seconds + + + + Time to wait for a connection, in seconds. If the option is not provided, + the default timeout is 30 seconds. + + + + + + + + + + + + Exit immediately if NetworkManager is not running or connecting. + + + From c7edb34eb91dff4fb67d09129eb5ab9e6eef9f10 Mon Sep 17 00:00:00 2001 From: Beniamino Galvani Date: Wed, 31 Oct 2018 13:48:35 +0100 Subject: [PATCH 4/4] cli: add --rescan option to help output --- clients/cli/devices.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 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 ...\n\n" " delete ...\n\n" " monitor ...\n\n" - " wifi [list [ifname ] [bssid ]]\n\n" + " wifi [list [ifname ] [bssid ] [--rescan yes|no|auto]]\n\n" " wifi connect <(B)SSID> [password ] [wep-key-type key|phrase] [ifname ]\n" " [bssid ] [name ] [private yes|no] [hidden yes|no]\n\n" " wifi hotspot [ifname ] [con-name ] [ssid ] [band a|bg] [channel ] [password ]\n\n" @@ -838,10 +838,11 @@ usage_device_wifi (void) "\n" "Perform operation on Wi-Fi devices.\n" "\n" - "ARGUMENTS := [list [ifname ] [bssid ]]\n" + "ARGUMENTS := [list [ifname ] [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 ] [wep-key-type key|phrase] [ifname ]\n" " [bssid ] [name ] [private yes|no] [hidden yes|no]\n"