From 3c625b367db926864e623fa2e12433c969401e3b Mon Sep 17 00:00:00 2001
From: Rusty Russell <rusty@rustcorp.com.au>
Date: Mon, 11 May 2020 10:41:51 +0930
Subject: [PATCH] doc: update cli documentation.

1. help now uses a boutique format, not -H.
2. document the -F option.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
---
 cli/lightning-cli.c    |  2 +-
 doc/lightning-cli.1    | 24 ++++++++++++++++++++----
 doc/lightning-cli.1.md | 17 +++++++++++++----
 3 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/cli/lightning-cli.c b/cli/lightning-cli.c
index cc8980c99..692aafd7b 100644
--- a/cli/lightning-cli.c
+++ b/cli/lightning-cli.c
@@ -503,7 +503,7 @@ int main(int argc, char *argv[])
 	opt_register_noarg("--help|-h", opt_usage_and_exit,
 			   "<command> [<params>...]", "Show this message. Use the command help (without hyphens -- \"lightning-cli help\") to get a list of all RPC commands");
 	opt_register_noarg("-H|--human-readable", opt_set_human, &format,
-			   "Human-readable output (default for 'help')");
+			   "Human-readable output");
 	opt_register_noarg("-F|--flat", opt_set_flat, &format,
 			   "Flatten output ('x.y.x=' format)");
 	opt_register_noarg("-J|--json", opt_set_json, &format,
diff --git a/doc/lightning-cli.1 b/doc/lightning-cli.1
index 1b23af3ad..2d04a55fa 100644
--- a/doc/lightning-cli.1
+++ b/doc/lightning-cli.1
@@ -41,24 +41,40 @@ Follow strictly the order of parameters for the command
 
 
  \fB--json\fR/\fB-J\fR
-Return result in JSON format (default unless \fIhelp\fR command)
+Return result in JSON format (default unless \fIhelp\fR command,
+or result contains a \fBformat-hint\fR field)\.
 
 
  \fB--raw\fR/\fB-R\fR
-Return raw JSON directly as lightningd replies
+Return raw JSON directly as lightningd replies; this can be faster for
+large requests\.
 
 
  \fB--human-readable\fR/\fB-H\fR
-Return result in human-readable output (default for \fIhelp\fR command)
+Return result in human-readable output\.
+
+
+ \fB--flat\fR/\fB-F\fR
+Return JSON result in flattened one-per-line output, e\.g\. \fB{ "help":
+[ { "command": "check" } ] }\fR would become \fBhelp[0].command=check\fR\.
+This is useful for simple scripts which want to find a specific output
+field without parsing JSON\.
 
 
  \fB--help\fR/\fB-h\fR
-Print summary of options to standard output and exit\.
+Pretty-print summary of options to standard output and exit\.  The format can
+be changed using -F, -R, -J, -H etc\.
 
 
  \fB--version\fR/\fB-V\fR
 Print version number to standard output and exit\.
 
+
+ \fBallow-deprecated-apis\fR=\fIBOOL\fR
+Enable deprecated options\. It defaults to \fItrue\fR, but you should set
+it to \fIfalse\fR when testing to ensure that an upgrade won’t break your
+configuration\.
+
 .SH COMMANDS
 
 \fIlightning-cli\fR simply uses the JSON RPC interface to talk to
diff --git a/doc/lightning-cli.1.md b/doc/lightning-cli.1.md
index 09d03cd38..d060ed9c3 100644
--- a/doc/lightning-cli.1.md
+++ b/doc/lightning-cli.1.md
@@ -38,16 +38,25 @@ Use format *key*=*value* for parameters in any order
 Follow strictly the order of parameters for the command
 
  **--json**/**-J**
-Return result in JSON format (default unless *help* command)
+Return result in JSON format (default unless *help* command,
+or result contains a `format-hint` field).
 
  **--raw**/**-R**
-Return raw JSON directly as lightningd replies
+Return raw JSON directly as lightningd replies; this can be faster for
+large requests.
 
  **--human-readable**/**-H**
-Return result in human-readable output (default for *help* command)
+Return result in human-readable output.
+
+ **--flat**/**-F**
+Return JSON result in flattened one-per-line output, e.g. `{ "help":
+[ { "command": "check" } ] }` would become `help[0].command=check`.
+This is useful for simple scripts which want to find a specific output
+field without parsing JSON.
 
  **--help**/**-h**
-Print summary of options to standard output and exit.
+Pretty-print summary of options to standard output and exit.  The format can
+be changed using -F, -R, -J, -H etc.
 
  **--version**/**-V**
 Print version number to standard output and exit.