doc: Mention keyword arguments, update pay to mention use of null.

doc/lightning-cli.1

@@ -2,12 +2,12 @@
 .\"     Title: lightning-cli
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 01/22/2018
+.\"      Date: 02/11/2018
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-CLI" "1" "01/22/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-CLI" "1" "02/11/2018" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -50,6 +50,32 @@ Named pipe to use to talk to lightning daemon: default is
 in the lightning directory\&.
 .RE
 .PP
+\fB\-\-keywords\fR/\fB\-k\fR
+.RS 4
+Use format
+\fIkey\fR=\fIvalue\fR
+for parameters in any order
+.RE
+.PP
+\fB\-\-order\fR/\fB\-o\fR
+.RS 4
+Follow strictly the order of parameters for the command
+.RE
+.PP
+\fB\-\-json\fR/\fB\-J\fR
+.RS 4
+Return result in JSON format (default unless
+\fIhelp\fR
+command)
+.RE
+.PP
+\fB\-\-human\-readable\fR/\fB\-H\fR
+.RS 4
+Return result in human\-readable output (default for
+\fIhelp\fR
+command)
+.RE
+.PP
 \fB\-\-help\fR/\fB\-h\fR
 .RS 4
 Print summary of options to standard output and exit\&.
@@ -64,7 +90,7 @@ Print version number to standard output and exit\&.
 \fIlightning\-cli\fR simply uses the JSON RPC interface to talk to \fIlightningd\fR, and prints the results\&. Thus the commands available depend entirely on the lightning daemon itself\&.
 .SH "ARGUMENTS"
 .sp
-Arguments are provided positionally after the command name\&. Arguments may be integer numbers (composed entirely of digits), floating\-point numbers (has a radix point but otherwise composed of digits), \fItrue\fR, \fIfalse\fR, or \fInull\fR\&. Other arguments are treated as strings\&.
+Arguments may be provided positionally or using \fIkey\fR=\fIvalue\fR after the command name, based on either \fB\-o\fR or \fB\-k\fR option\&. Arguments may be integer numbers (composed entirely of digits), floating\-point numbers (has a radix point but otherwise composed of digits), \fItrue\fR, \fIfalse\fR, or \fInull\fR\&. Other arguments are treated as strings\&.
 .sp
 Some commands have optional arguments\&. You may use \fInull\fR to skip optional arguments to provide later arguments\&.
 .SH "EXAMPLES"

doc/lightning-cli.1.txt

@@ -23,6 +23,14 @@ OPTIONS
 *--rpc-file*='FILE'::
   Named pipe to use to talk to lightning daemon: default is 'lightning-rpc'
   in the lightning directory.
+*--keywords*/*-k*::
+  Use format 'key'='value' for parameters in any order
+*--order*/*-o*::
+  Follow strictly the order of parameters for the command
+*--json*/*-J*::
+  Return result in JSON format (default unless 'help' command)
+*--human-readable*/*-H*::
+  Return result in human-readable output (default for 'help' command)
 *--help*/*-h*::
   Print summary of options to standard output and exit.
 *--version*/*-V*::
@@ -36,7 +44,8 @@ lightning daemon itself.
 
 ARGUMENTS
 ---------
-Arguments are provided positionally after the command name.
+Arguments may be provided positionally or using 'key'='value'
+after the command name, based on either *-o* or *-k* option.
 Arguments may be integer numbers (composed entirely of digits),
 floating-point numbers (has a radix point but otherwise composed
 of digits), 'true', 'false', or 'null'.

doc/lightning-pay.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-pay
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 02/08/2018
+.\"      Date: 02/11/2018
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-PAY" "7" "02/08/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-PAY" "7" "02/11/2018" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -37,6 +37,8 @@ lightning-pay \- Protocol for sending a payment to a BOLT11 invoice
 The \fBpay\fR RPC command attempts to find a route to the given destination, and send the funds it asks for\&. If the \fIbolt11\fR does not contain an amount, \fImsatoshi\fR is required, otherwise if it is specified it must be \fInull\fR\&. If \fIbolt11\fR contains a description hash (\fIh\fR field) \fIdescription\fR is required, otherwise it is unused\&. The \fIriskfactor\fR is described in detail in lightning\-getroute(7), and defaults to 1\&.0\&. The \fImaxfeepercent\fR limits the money paid in fees, and defaults to 0\&.5\&. The \(oqmaxfeepercent\(cq is a percentage of the amount that is to be paid\&.
 .sp
 The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&.
+.sp
+When using \fIlightning\-cli\fR, you may skip optional parameters by using \fInull\fR\&. Alternatively, use \fB\-k\fR option to provide parameters by name\&.
 .SH "RETURN VALUE"
 .sp
 On success, this returns the payment \fIpreimage\fR which hashes to the \fIpayment_hash\fR to prove that the payment was successful\&.

doc/lightning-pay.7.txt

@@ -27,6 +27,10 @@ The response will occur when the payment fails or succeeds.  Once a
 payment has succeeded, calls to *pay* with the same 'bolt11' will
 succeed immediately.
 
+When using 'lightning-cli', you may skip optional parameters by using
+'null'.
+Alternatively, use *-k* option to provide parameters by name.
+
 RETURN VALUE
 ------------