From 4e382ebd940db7ca86f72cfd1e71f430d0ee661b Mon Sep 17 00:00:00 2001 From: ZmnSCPxj Date: Sun, 11 Feb 2018 23:25:43 +0000 Subject: [PATCH] doc: Mention keyword arguments, update pay to mention use of null. --- doc/lightning-cli.1 | 32 +++++++++++++++++++++++++++++--- doc/lightning-cli.1.txt | 11 ++++++++++- doc/lightning-pay.7 | 6 ++++-- doc/lightning-pay.7.txt | 4 ++++ 4 files changed, 47 insertions(+), 6 deletions(-) diff --git a/doc/lightning-cli.1 b/doc/lightning-cli.1 index edfd866b9..652487ac6 100644 --- a/doc/lightning-cli.1 +++ b/doc/lightning-cli.1 @@ -2,12 +2,12 @@ .\" Title: lightning-cli .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" 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" diff --git a/doc/lightning-cli.1.txt b/doc/lightning-cli.1.txt index 17c8a4772..371959e3d 100644 --- a/doc/lightning-cli.1.txt +++ b/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'. diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 index 048149fd3..c64c94114 100644 --- a/doc/lightning-pay.7 +++ b/doc/lightning-pay.7 @@ -2,12 +2,12 @@ .\" Title: lightning-pay .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" 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\&. diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt index 9c79b675b..405bc04d3 100644 --- a/doc/lightning-pay.7.txt +++ b/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 ------------