doc: language tidyups and a few minor refinements.

Some additional detail was warranted in several places, though the
listconfigs is better off simply referring to lightningd-config.

Signed-off-by: Rusty Russell <[email protected]>
Changelog-Fixed: doc: Many missing manual pages were completed

doc/lightning-getinfo.7.md

@@ -9,7 +9,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-The **getinfo** is a RPC command which is possible receive all node informations.
+The **getinfo** gives a summary of the current running node.
 
 
 EXAMPLE JSON REQUEST
@@ -27,21 +27,21 @@ RETURN VALUE
 
 On success, an object with the following information is returned:
 
-- *id*: A string that rappresents the public key of the node. It will rappresent the node on the public network.
-- *alias*: A string that rappresents the alias of the node, by default is calculate from the public key (node id).
-- *color*: A string that rappresents the color of the node.
-- *num_peers*: An integer that rappresents the number of peer connect to the node.
-- *num_pending_channels*: An integer that rappresents the number of channel with pending status.
-- *num_active_channels*: A integer that rappresents the number of channel with the active status.
-- *num_inactive_channels*: A integer that rappresents the number of channel with the inactive status.
-- *address*: An array that rappresents all addresses of the node, each object inside the array contains the following proprieties:
-  - *type*: A string that rappresents the type of the address (ipv4 or ipv6).
-  - *address*: A string that rappresents the value of the address.
-  - *port*: An integer that rappresents the port where the node are listening with this address.
-- *binding*: An array that rappresents all addresses where the node is binded. Each object contains the same object type of the address propriety above.
-- *version*: A string that rappresents the version of the node.
-- *blockheight*: An integer that rappresents the blockchain height.
-- *network*: A string that rappresents the type of network on the node are working (i.e: bitcoin, testnet, regtest).
+- *id*: A string that represents the public key of the node. It will represents the node on the public network.
+- *alias*: A string that represents the alias of the node, by default is calculate from the public key (node id).  This is just for fun; the name can be anything and is not unique!
+- *color*: A string that represents the preferred color of the node.
+- *num_peers*: An integer that represents the number of peer connect to the node.
+- *num_pending_channels*: An integer that represents the number of channel which are still awaiting opening confirmation.
+- *num_active_channels*: A integer that represents the number of channel which are currently open.
+- *num_inactive_channels*: A integer that represents the number of channel which are closing.
+- *address*: An array that represents all published addresses of the node, each object inside the array contains the following proprieties:
+  - *type*: A string that represents the type of the address (currently `ipv4`, `ipv6`, `torv3` or `torv4`).
+  - *address*: A string that represents the value of the address.
+  - *port*: An integer that represents the port where the node is listening with this address.
+- *binding*: An array that represents all addresses where the node is binded. Each object contains the same object type of the address propriety above.
+- *version*: A string that represents the version of the node.
+- *blockheight*: An integer that represents the blockchain height.
+- *network*: A string that represents the type of network on the node are working (e.g: `bitcoin`, `testnet`, or `regtest`).
 
 On failure, one of the following error codes may be returned:
 

doc/lightning-getlog.7.md

@@ -4,14 +4,14 @@ lightning-getlog -- Command to show logs.
 SYNOPSIS
 --------
 
-**getlog** \[level\]
+**getlog** \[*level*\]
 
 DESCRIPTION
 -----------
 
 The **getlog** the RPC command to show logs, with optional log *level*.
 
-- *level*: A string that rappresent the log level (info, unusual, debug, io).
+- *level*: A string that represents the log level (*broken*, *unusual*, *info*, *debug*, or *io*).  The default is *info*.
 
 EXAMPLE JSON REQUEST
 --------------------
@@ -30,14 +30,14 @@ RETURN VALUE
 
 On success, a object will be return with the following parameters:
 
-- *created_at*: An floating point value that rappresent the {}. 
-- *bytes_used*: A string that rappresent the dimension in bytes of the log file.
-- *bytes_max*: An integer that rappresent the max dimension in bytes of log file.
-- *log*: An array of object where each elements contains the following proprieties:
- - *type*: A string that rappresent the log level. The propriety can have an value equal to SKIPPED.
- - *time*: A floating point value that rappresent the time.
- - *source*: A string that rappresent the source of line.
- - *log*: A string that rappresent the content of line.
+- *created_at*: An floating point value that represents the UNIX timestamp when logging began. 
+- *bytes_used*: A string that represents the dimension in bytes of the log file.
+- *bytes_max*: An integer that represents the max dimension in bytes of log file.
+- *log*: An array of objects where each element contains the following proprieties:
+ - *type*: A string that represents the log level. The propriety can have an value equal to SKIPPED to indicate the existence of omitted entries.
+ - *time*: A floating point value that represents the time since *created_at*.
+ - *source*: A string that represents the source of line.
+ - *log*: A string that represents the content of line.
 - *num_skipped*: An integer that it is present only if the log level is equal to SKIPPED.
 
 

doc/lightning-help.7.md

@@ -4,12 +4,16 @@ lightning-help -- Command to return all information about RPC commands.
 SYNOPSIS
 --------
 
-**help**
+**help** \[*command\*]
 
 DESCRIPTION
 -----------
 
-The **help** is a RPC command which is possible consult all information about the RPC commands.
+The **help** is a RPC command which is possible consult all information about the RPC commands, or a specific command if *command* is given.
+
+Note that the lightning-cli(1) tool will prefer to list a man page when a
+specific *command* is specified, and will only return the JSON if the man
+page is not found.
 
 EXAMPLE JSON REQUEST
 --------------------
@@ -26,10 +30,10 @@ RETURN VALUE
 
 On success, a object will be return with the following proprieties:
 
-- *command*: A string that rappresent the stucture of the command.
-- *category*: A string that rappresent the category.
-- *description*: A string that rappresent the description.
-- *verbose*: A string that rappresent the verbode description.
+- *command*: A string that represents the stucture of the command.
+- *category*: A string that represents the category.
+- *description*: A string that represents the description.
+- *verbose*: A string that represents the verbode description.
 
 On failure, one of the following error codes may be returned: