man: update nmcli man page

- fix some errors and formatting
- add EXAMPLES section with several examples of nmcli invocation

man/nmcli.1.in

@@ -22,10 +22,10 @@
 .\"
 .\" Copyright (C) 2010 - 2012 Red Hat, Inc.
 .\"
-.TH NMCLI "1" "30 April 2012"
+.TH NMCLI "1" "29 May 2012"
 
 .SH NAME
-nmcli \- command-line tool for controlling NetworkManager
+nmcli \(en command\(hyline tool for controlling NetworkManager
 .SH SYNOPSIS
 .ad l
 .B nmcli
@@ -57,8 +57,8 @@ nmcli \- command-line tool for controlling NetworkManager
 
 .SH DESCRIPTION
 .B nmcli
-is a command-line tool for controlling NetworkManager and reporting on its status.
+is a command\(hyline tool for controlling NetworkManager and reporting on its status.
-It is not meant as a full replacement for \fInm-applet\fP or other similar clients
+It is not meant as a full replacement for \fInm\(hyapplet\fP or other similar clients
 but as a complementary utility to those programs.
 The main usage for \fInmcli\fP is on servers, headless machines or for power users
 who prefer the command line.
@@ -75,7 +75,7 @@ in order to activate and if that secret is not stored at the system level,
 the secrets to NetworkManager.
 .IP \(em 4
 User sessions: \fInmcli\fP can be used to activate/deactivate connections from
-the command line, but a client with a secret agent (like \fInm-applet\fP) is needed
+the command line, but a client with a secret agent (like \fInm\(hyapplet\fP) is needed
 for supplying secrets not stored at the system level. Keyring dialogs and
 password prompts may appear if this happens.
 .SS \fIOPTIONS\fP
@@ -98,21 +98,21 @@ line, default is \fImultiline\fP. Currenly, they are:
   'nmcli con list id|uuid <name>'
   'nmcli dev list'
 .fi
-\fItabular\fP   - Output is a table where each line describes a single entry.
+\fItabular\fP   \(en Output is a table where each line describes a single entry.
 Columns define particular properties of the entry.
 .br
-\fImultiline\fP - Each entry comprises multiple lines, each property on its own
+\fImultiline\fP \(en Each entry comprises multiple lines, each property on its own
 line. The values are prefixed with the property name.
 .TP
 .B \-f, \-\-fields <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 \fI--fields\fP option.
+providing an invalid value to the \fI\-\-fields\fP option.
 .br
 \fIall\fP is used to print all valid field values of the command.
 \fIcommon\fP is used to print common field values of the command.
 If omitted, default is \fIcommon\fP.
-The option is mandatory when \fI--terse\fP is used.  In this case, generic
+The option is mandatory when \fI\-\-terse\fP is used.  In this case, generic
 values \fIall\fP and \fIcommon\fP cannot be used.  (This is to maintain
 compatibility when new fields are added in the future).
 .TP
@@ -143,18 +143,18 @@ Show overall status of NetworkManager. This is the default action, when no
 command is provided to \fInm\fP object.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
 .B permissions
 .br
 Show the permissions a caller has for various authenticated operations that
-NetworkManager provides, like enable/disable networking, changing Wi-Fi, WWAN,
+NetworkManager provides, like enable/disable networking, changing Wi\(hyFi, WWAN,
 and WiMAX state, modifying connections, etc.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager
 method:    GetPermissions
 arguments: none
@@ -162,12 +162,12 @@ arguments: none
 .TP
 .B enable [true|false]
 .br
-Get networking-enabled status or enable/disable networking by NetworkManager.
+Get networking\(hyenabled status or enable/disable networking by NetworkManager.
 All interfaces managed by NetworkManager are deactivated when networking has
 been disabled.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager
 method:    Enable
 arguments: TRUE or FALSE
@@ -177,12 +177,12 @@ arguments: TRUE or FALSE
 .br
 Get sleep status or put to sleep/awake NetworkManager. All interfaces managed
 by NetworkManager are deactivated when it falls asleep. This command is not
-meant for user to enable/disable networking, use \fIenable\fP for that. D-Bus
+meant for user to enable/disable networking, use \fIenable\fP for that. D\(hyBus
 \fISleep\fP method is designed to put NetworkManager to sleep or awake for
 suspending/resuming the computer.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager
 method:    Sleep
 arguments: TRUE or FALSE
@@ -190,11 +190,11 @@ arguments: TRUE or FALSE
 .TP
 .B wifi [on|off]
 .br
-Inquire or set status of Wi-Fi in NetworkManager. If no arguments are supplied,
+Inquire or set status of Wi\(hyFi in NetworkManager. If no arguments are supplied,
-Wi-Fi status is printed; \fIon\fP enables Wi-Fi; \fIoff\fP disables Wi-Fi.
+Wi\(hyFi status is printed; \fIon\fP enables Wi\(hyFi; \fIoff\fP disables Wi\(hyFi.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
@@ -204,7 +204,7 @@ Inquire or set status of WWAN in NetworkManager. If no arguments are supplied,
 WWAN status is printed; \fIon\fP enables WWAN; \fIoff\fP disables WWAN.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
@@ -213,10 +213,10 @@ No simple reference.
 Inquire or set status of WiMAX in NetworkManager. If no arguments are supplied,
 WiMAX status is printed; \fIon\fP enables WiMAX; \fIoff\fP disables WiMAX.
 .br
-Note: WiMAX support is a compile-time decision, so it may be unavailable on some
+Note: WiMAX support is a compile\(hytime decision, so it may be unavailable on some
 installations.
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .RE
@@ -239,7 +239,7 @@ name or \fIuuid\fP with connection's UUID shall be specified.  When no command
 is given to the \fIcon\fP object, the default action is 'nmcli con list'.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
@@ -248,26 +248,41 @@ No simple reference.
 Print status of active connections.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
-.B up id <id> | uuid <id> [iface <iface>] [ap <BSSID>] [\-\-nowait] [\-\-timeout <timeout>]
+.B up id <id> | uuid <id> [iface <iface>] [ap <BSSID>] [nsp <name>] [\-\-nowait] [\-\-timeout <timeout>]
 .br
 Activate a connection.  The connection is identified by its name using \fIid\fP
 or UUID using \fIuuid\fP. When requiring a particular device to activate the
-connection on, the \fIiface\fP option with interface name should be given.
+connection on, the \fIiface\fP option with interface name should be given. In
-The \fIap\fP option can further specify what AP should be used in case of a Wi-Fi
+case of a VPN connection, the \fIiface\fP option specify the device of the base
-connection. The \fI\-\-nowait\fP option causes \fInmcli\fP to exit immediately and
+connection. The \fIap\fP option specify what particular AP should be used in case
-not to wait for command completion. The \fI\-\-timeout\fP option provides a means
+of a Wi\(hyFi connection.
-to specify how long to wait for operation completion.
+.RS
+.PP
+Available options are:
+.IP \fIiface\fP 13
+\(en interface that will be used for activation
+.IP \fIap\fP 13
+\(en BSSID of the AP which the command should connect to (for Wi\(hyFi connections)
+.IP \fInsp\fP 13
+\(en NSP (Network Service Provider) which the command should connect to (for WiMAX connections)
+.IP \fI\-\-nowait\fP 13
+\(en exit immediately without waiting for command completion
+.IP \fI\-\-timeout\fP 13
+\(en how long to wait for command completion (default is 90 s)
+.PP
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager
 method:    ActivateConnection
 arguments: according to arguments
 .fi
+.RE
+
 .TP
 .B down id <id> | uuid <id>
 .br
@@ -276,7 +291,7 @@ The connection is identified by its name using \fIid\fP
 or UUID using \fIuuid\fP.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager
 method:    DeactivateConnection
 arguments: according to arguments
@@ -288,7 +303,7 @@ Delete a configured connection. The connection to delete is specified with
 \fIid\fP (connection name) or \fIuuid\fP (connection UUID).
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager.Settings.Connection
 method:    Delete
 arguments: none
@@ -311,7 +326,7 @@ Print status of devices.  This is the default action, when no command
 is specified to \fIdev\fP object.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
@@ -322,69 +337,75 @@ examined. To get information for a specific device, the \fIiface\fP argument
 with the interface name should be provided.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
 .B disconnect iface <iface> [\-\-nowait] [\-\-timeout <timeout>]
 .br
 Disconnect a device and prevent the device from automatically activating further
-connections without user/manual intervention. The \fI\-\-nowait\fP option causes
+connections without user/manual intervention.
-\fInmcli\fP to exit immediately and not to wait for command completion.
+.RS
-The \fI\-\-timeout\fP option provides a means to specify how long to wait for
+.PP
-operation completion.
+Available options are:
+.IP \fI\-\-nowait\fP 13
+\(en exit immediately without waiting for command completion
+.IP \fI\-\-timeout\fP 13
+\(en how long to wait for command completion (default is 10 s)
+.PP
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager.Device
 method:    Disconnect
 arguments: none
 .fi
+.RE
 .TP
 .B wifi [list [iface <iface>] [bssid <BSSID>]]
 .br
-List available Wi-Fi access points. The \fIiface\fP and \fIbssid\fP options
+List available Wi\(hyFi access points. The \fIiface\fP and \fIbssid\fP options
 can be used to list APs for a particular interface or with a specific BSSID,
 respectively.
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 No simple reference.
 .fi
 .TP
-.B wifi connect <(B)SSID> [password <password>] [wep-key-type key|phrase] [iface <iface>] [bssid <BSSID>] [name <name>] [--private] [--nowait] [--timeout <timeout>]
+.B wifi connect <(B)SSID> [password <password>] [wep\-key\-type key|phrase] [iface <iface>] [bssid <BSSID>] [name <name>] [\-\-private] [\-\-nowait] [\-\-timeout <timeout>]
 .br
-Connect to a Wi-Fi network specified by SSID or BSSID. The command creates a new
+Connect to a Wi\(hyFi 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
+connection and then activates it on a device. This is a command\(hyline 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
+and thus it is mainly useful for connecting to new Wi\(hyFi networks. If a connection
 for the network already exists, it's better to connect through it using
-\fInmcli con up id <name>\fP. Note that only open, WEP and WPA-PSK networks are
+\fInmcli con up id <name>\fP. Note that only open, WEP and WPA\(hyPSK networks are
 supported at the moment. It is also supposed that IP configuration is obtained via
 DHCP.
 .RS
 .PP
 Available options are:
 .IP \fIpassword\fP 13
-- password for secured networks (WEP or WPA)
+\(en password for secured networks (WEP or WPA)
-.IP \fIwep-key-type\fP 13
+.IP \fIwep\-key\-type\fP 13
-- type of WEP secret, either \fIkey\fP for ASCII/HEX key or \fIphrase\fP for passphrase
+\(en type of WEP secret, either \fIkey\fP for ASCII/HEX key or \fIphrase\fP for passphrase
 .IP \fIiface\fP 13
-- interface that will be used for activation
+\(en interface that will be used for activation
 .IP \fIbssid\fP 13
-- if specified, the created connection will be restricted just for the BSSID
+\(en if specified, the created connection will be restricted just for the BSSID
 .IP \fIname\fP 13
-- if specified, the connection will use the name (else NM creates a name itself)
+\(en if specified, the connection will use the name (else NM creates a name itself)
 .IP \fI\-\-private\fP 13
-- the connection will only be visible to the user who created it (else the connection is system-wide)
+\(en the connection will only be visible to the user who created it (else the connection is system\(hywide)
 .IP \fI\-\-nowait\fP 13
-- exit immediately without waiting for command completion
+\(en exit immediately without waiting for command completion
 .IP \fI\-\-timeout\fP 13
-- how long to wait for command completion (default is 90 s)
+\(en how long to wait for command completion (default is 90 s)
 .PP
 .br
 .nf
-\fBReference to D-Bus:\fP
+\fBReference to D\(hyBus:\fP
 interface: org.freedesktop.NetworkManager
 method:    AddAndActivateConnection
 arguments: according to arguments
@@ -394,19 +415,19 @@ arguments: according to arguments
 .SH ENVIRONMENT VARIABLES
 \fInmcli\fP's behavior is affected by the following environment variables.
 .IP "LC_ALL" 13
-If set to a non-empty string value, it overrides the values of all the other
+If set to a non\(hyempty string value, it overrides the values of all the other
 internationalization variables.
 .IP "LC_MESSAGES" 13
-Determines the locale to be used for internationalised messages.
+Determines the locale to be used for internationalized messages.
 .IP "LANG" 13
 Provides a default value for the internationalization variables that are unset
 or null.
 
 .RE
-Notes about localization:
+Internationalization notes:
 .br
 Be aware that \fInmcli\fP is localized and that's why the output depends on
-your environment. It's important to realize that especially when you parse the
+your environment. This is important to realize especially when you parse the
 output.
 .br
 Call \fInmcli\fP as \fBLC_ALL=C nmcli\fP to be sure the locale is
@@ -421,7 +442,7 @@ and this locale uses English messages.
 \fInmcli\fP exits with status 0 if it succeeds, a value greater than 0 is
 returned if an error occurs.
 .IP "0" 4
-Success - indicates the operation succeeded
+Success \(en indicates the operation succeeded
 .IP "1" 4
 Unknown or unspecified error
 .IP "2" 4
@@ -435,9 +456,70 @@ Connection deactivation failed
 .IP "6" 4
 Disconnecting device failed
 
+.SH EXAMPLES
+.IP "\fB\f(CWnmcli \-t \-f RUNNING nm\fP\fP"
+.IP
+tells you whether NetworkManager is running or not.
+
+.IP "\fB\f(CWnmcli \-t \-f STATE nm\fP\fP"
+.IP
+shows the overall status of NetworkManager.
+
+.IP "\fB\f(CWnmcli nm wifi off\fP\fP"
+.IP
+switches Wi\(hyFi off.
+
+.IP "\fB\f(CWnmcli \-p con list\fP\fP"
+.IP
+lists all connections NetworkManager has.
+
+.IP "\fB\f(CWnmcli \-f name,autoconnect con list\fP\fP"
+.IP
+lists all connections' names and their autoconnect settings.
+
+.IP "\fB\f(CWnmcli con list id \(dq\&My wired connection\(dq\&\fP\fP"
+.IP
+lists all details of the connection with "My wired connection" name.
+
+.IP "\fB\f(CWnmcli \-p con up id \(dq\&My wired connection\(dq\& iface eth0\fP\fP"
+.IP
+activates the connection with name "My wired connection" on interface eth0.
+The \-p option makes nmcli show progress of the activation.
+
+.IP "\fB\f(CWnmcli con up uuid 6b028a27\-6dc9\-4411\-9886\-e9ad1dd43761 ap 00:3A:98:7C:42:D3\fP\fP"
+.IP
+connects the Wi\(hyFi connection with UUID 6b028a27\-6dc9\-4411\-9886\-e9ad1dd43761 to the AP
+with BSSID 00:3A:98:7C:42:D3.
+
+.IP "\fB\f(CWnmcli dev status\fP\fP"
+.IP
+shows the status for all devices.
+
+.IP "\fB\f(CWnmcli dev disconnect iface em2\fP\fP"
+.IP
+disconnects a connection on interface em2 and marks the device as unavailable for
+auto\(hyconnecting. That's why no connection will automatically be activated on the
+device until the device's "autoconnect" is set to TRUE or user manually activates
+a connection.
+
+.IP "\fB\f(CWnmcli \-f GENERAL,WIFI\-PROPERTIES dev list iface wlan0\fP\fP"
+.IP
+lists details for wlan0 interface; only GENERAL and WIFI\-PROPERTIES sections will be shown.
+
+.IP "\fB\f(CWnmcli dev wifi\fP\fP"
+.IP
+lists available Wi\(hyFi access points known to NetworkManager.
+
+.IP "\fB\f(CWnmcli dev wifi con \(dq\&Cafe Hotspot 1\(dq\& password caffeine name \(dq\&My cafe\(dq\&\fP\fP"
+.IP
+creates a new connection named "My cafe" and then connects it to "Cafe Hotspot 1" SSID
+using "caffeine" password. This is mainly useful when connecting to "Cafe Hotspot 1" for
+the first time. Next time, it is better to use 'nmcli con up id "My cafe"' so that the
+existing connection profile can be used and no additional is created.
+
 .SH BUGS
-There are probably some.  If you find a bug, please report to
+There are probably some bugs.  If you find a bug, please report it to
-https://bugzilla.gnome.org/ \- product \fINetworkManager\fP.
+https://bugzilla.gnome.org/ \(em product \fINetworkManager\fP.
 
 .SH SEE ALSO
 .BR nm\-tool (1),