doc: fix connect manpage parameter names and...

also fixed grammar and consistency with other manpages.

The names are now the same as what json_connect() expects.

Signed-off-by: Mark Beckwith <wythe@intrig.com>

doc/lightning-connect.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-connect
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 04/26/2018
+.\"      Date: 02/11/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-CONNECT" "7" "04/26/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-CONNECT" "7" "02/11/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -31,31 +31,41 @@
 lightning-connect \- Command for connecting to another lightning node\&.
 .SH "SYNOPSIS"
 .sp
-\fBconnect\fR \fInode_id\fR[@(\fIip_addr\fR|\fIhostname\fR)[:\*(Aqport\*(Aq]]
+\fBconnect\fR \fIid\fR [\fIhost\fR \fIport\fR]
-.sp
-or
-.sp
-\fBconnect\fR \fInode_id\fR[ (\fIip_addr\fR|\fIhostname\fR)[:\*(Aqport\*(Aq]]
 .SH "DESCRIPTION"
 .sp
 The \fBconnect\fR RPC command establishes a new connection with another node in the Lightning Network\&.
 .sp
-\fInode_id\fR represents the target node\(cqs public key and \fIip_addr\fR can be either IPv4 or IPv6\&.
+\fIid\fR represents the target node\(cqs public key\&. As a convenience, \fIid\fR may be of the form \fIid@host\fR or \fIid@host:port\fR\&. In this case, the \fIhost\fR and \fIport\fR parameters must be omitted\&.
 .sp
-If not specified the \fIport\fR is assumed to be 9375 (default lightning port)\&.
+\fIhost\fR is the peer\(cqs hostname or IP address\&.
 .sp
-If neither \fIip_addr\fR or \fIhostname\fR is specified, connection will be attempted to an IP belonging to \fInode_id\fR learned through gossip with other already connected peers
+If not specified, the \fIport\fR defaults to 9375\&.
 .sp
-Connecting to a node is just the first step in opening a channel with another node, once the peer is connected a channel can be opened with lightning\-fundchannel(7)
+If \fIhost\fR is not specified, the connection will be attempted to an IP belonging to \fIid\fR obtained through gossip with other already connected peers\&.
+.sp
+Connecting to a node is just the first step in opening a channel with another node\&. Once the peer is connected a channel can be opened with lightning\-fundchannel(7)\&.
 .SH "RETURN VALUE"
 .sp
-On success the response will include just the peer id (peer\(cqs public key)
+On success the peer \fIid\fR is returned\&.
-.SH "ERRORS"
 .sp
-If \fInode_id\fR or \fIip_addr\fR are invalid or if \fIhostname\fR can\(cqt be resolved to a valid IP address an error message will be returned\&. An error will also be returned if the simplified version (only \fInode_id\fR) is used and there\(cqs no published IP for the peer\&. \fBconnect\fR will make up to 10(?) attempts to connect to the peer before giving up
+The following error codes may occur:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\-1\&. Catchall nonspecific error\&. This may occur if the host is not valid or there are problems communicating with the peer\&.
+\fBconnect\fR
+will make up to 10 attempts to connect to the peer before giving up\&.
+.RE
 .SH "AUTHOR"
 .sp
-Felix <fixone@gmail\&.com> is mainly responsible\&.
+Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&. Felix <fixone@gmail\&.com> is the original author of this manpage\&.
 .SH "SEE ALSO"
 .sp
 lightning\-fundchannel(7), lightning\-listpeers(7), lightning\-listchannels(7), lightning\-disconnect(7)

doc/lightning-connect.7.txt

@@ -9,50 +9,48 @@ lightning node.
 
 SYNOPSIS
 --------
-*connect* 'node_id'[@('ip_addr'|'hostname')[:'port']]
+*connect* 'id' ['host' 'port']
-
-or
-
-*connect* 'node_id'[ ('ip_addr'|'hostname')[:'port']]
 
 DESCRIPTION
 -----------
 The *connect* RPC command establishes a new connection 
 with another node in the Lightning Network.
 
-'node_id' represents the target node's public key and 
+'id' represents the target node's public key.
-'ip_addr' can be either IPv4 or IPv6. 
+As a convenience, 'id' may be of the form 'id@host' or 'id@host:port'.
+In this case, the 'host' and 'port' parameters must be omitted.
 
-If not specified the 'port' is assumed to be 9375 
+'host' is the peer's hostname or IP address.
-(default lightning port).
 
-If neither 'ip_addr' or 'hostname' is specified, 
+If not specified, the 'port' defaults to 9375.
+
+If 'host' is not specified, the
 connection will be attempted to an IP belonging to 
-'node_id' learned through gossip with other already 
+'id' obtained through gossip with other already
-connected peers
+connected peers.
 
 Connecting to a node is just the first step in opening 
-a channel with another node, once the peer is connected
+a channel with another node.
-a channel can be opened with lightning-fundchannel(7)
+Once the peer is connected a channel can be opened with
+lightning-fundchannel(7).
 
 
 RETURN VALUE
 ------------
-On success the response will include just the peer id 
+On success the peer 'id' is returned.
-(peer's public key)
 
-ERRORS
+The following error codes may occur:
-------
+
-If 'node_id' or 'ip_addr' are invalid or if 'hostname' 
+* -1. Catchall nonspecific error.
-can't be resolved to a valid IP address an error message
+      This may occur if the host is not valid or there are problems
-will be returned. An error will also be returned if the 
+      communicating with the peer.
-simplified version (only 'node_id') is used and there's
+      *connect* will make up to 10 attempts to connect to the peer before
-no published IP for the peer. *connect* will make up to 
+      giving up.
-10(?) attempts to connect to the peer before giving up
 
 AUTHOR
 ------
-Felix <fixone@gmail.com> is mainly responsible.
+Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
+Felix <fixone@gmail.com> is the original author of this manpage.
 
 SEE ALSO
 --------