Merge #1848 #1849

1848: Update README.rst r=dcoutts a=kevinhammond

Updated cardano-cli documentation as requested by Tatyana

1849: Update README.md r=dcoutts a=kevinhammond

Updated CLI help output and minor fixes.


Co-authored-by: Kevin Hammond <12563287+kevinhammond@users.noreply.github.com>

README.rst

@@ -120,43 +120,40 @@ Please see ``scripts/README.md`` for information on the various scripts.
 ===============
 
 A CLI utility to support a variety of key material operations (genesis, migration, pretty-printing..) for different system generations.
+Usage documentation can be found at ``cardano-cli/README.md``.
 
 The general synopsis is as follows:
 
 .. code-block:: console
 
-   Usage: cardano-cli (Genesis related CMDs | Key related CMDs | Delegation related CMDs | Transaction related CMDs | Local node related CMDs)
-
+Usage: cardano-cli (Byron specific commands | Shelley specific commands |  Miscellaneous commands)
+                     
 > NOTE: the exact invocation command depends on the environment.  If you have only built ``cardano-cli``, without installing it, then you have to prepend ``cabal run -- ``
 before ``cardano-cli``.  We henceforth assume that the necessary environment-specific adjustment has been made, so we only mention ``cardano-cli``.
 
 The subcommands are subdivided in groups, and their full list can be seen in the output of ``cardano-cli --help``.
 
-All subcommands have help available:
+All subcommands have help available.  For example:
 
 .. code-block:: console
 
-   $ cabal v2-run -- cardano-cli migrate-delegate-key-from --help
-   Usage: cardano-cli migrate-delegate-key-from (--byron-legacy | --bft | --praos |
-                                                 --real-pbft)
-                                                 --from FILEPATH
-                                                (--byron-legacy | --bft | --praos |
-                                                 --real-pbft)
-                                                 --to FILEPATH
-   Migrate a delegate key from an older version.
-
-   Available options:
-     --byron-legacy           Byron/Ouroboros Classic suite of algorithms
-     --bft                    BFT consensus
-     --praos                  Praos consensus
-     --real-pbft              Permissive BFT consensus
-     --from FILEPATH          Signing key file to migrate.
-     --byron-legacy           Byron/Ouroboros Classic suite of algorithms
-     --bft                    BFT consensus
-     --praos                  Praos consensus
-     --real-pbft              Permissive BFT consensus
-     --to FILEPATH            Non-existent file to write the signing key to.
-     -h,--help                Show this help text
+ cabal v2-run -- cardano-cli migrate-delegate-key-from --help
+Up to date
+Usage: cardano-cli migrate-delegate-key-from (--byron-legacy-formats | 
+                                               --byron-formats) --from FILEPATH 
+                                             (--byron-legacy-formats | 
+                                               --byron-formats) --to FILEPATH
+  Migrate a delegate key from an older version.
+
+Available options:
+  --byron-legacy-formats   Byron/cardano-sl formats and compatibility
+  --byron-formats          Byron era formats and compatibility
+  --from FILEPATH          Signing key file to migrate.
+  --byron-legacy-formats   Byron/cardano-sl formats and compatibility
+  --byron-formats          Byron era formats and compatibility
+  --to FILEPATH            Non-existent file to write the signing key to.
+  -h,--help                Show this help text
+
 
 Genesis operations
 ==================
@@ -217,7 +214,7 @@ it needs to be migrated over, which is done by the ``migrate-delegate-key-from``
 .. code-block:: console
 
   $ cabal v2-run -- cardano-cli migrate-delegate-key-from
-          --byron-legacy --from key0.sk  --real-pbft --to key0.pbft
+          --byron-legacy-formats --from key0.sk  --real-pbft --to key0.pbft
 
 Signing key queries
 -------------------

cardano-cli/README.md

@@ -23,31 +23,7 @@ Available options:
   -h,--help                Show this help text
 
 Byron specific commands
-  byron                    Byron node operation commands
-  genesis                  Create genesis.
-  print-genesis-hash       Compute hash of a genesis file.
-  keygen                   Generate a signing key.
-  to-verification          Extract a verification key in its base64 form.
-  signing-key-public       Pretty-print a signing key's verification key (not a
-                           secret).
-  signing-key-address      Print address of a signing key.
-  migrate-delegate-key-from
-                           Migrate a delegate key from an older version.
-  issue-delegation-certificate
-                           Create a delegation certificate allowing the
-                           delegator to sign blocks on behalf of the issuer
-  check-delegation         Verify that a given certificate constitutes a valid
-                           delegation relationship between keys.
-  submit-tx                Submit a raw, signed transaction, in its on-wire
-                           representation.
-  issue-genesis-utxo-expenditure
-                           Write a file with a signed transaction, spending
-                           genesis UTxO.
-  issue-utxo-expenditure   Write a file with a signed transaction, spending
-                           normal UTxO.
-  get-tip                  Get the tip of your local node's blockchain
-  validate-cbor            Validate a CBOR blockchain object.
-  pretty-print-cbor        Pretty print a CBOR file.
+  byron                    Byron specific commands
 
 Shelley specific commands
   shelley                  Shelley specific commands
@@ -56,7 +32,57 @@ Miscellaneous commands
   version                  Show the cardano-cli version
 ```
 
-See [`../README.md`](../README.md) for full usage instructions and examples of use.
+Shelley-specific commands
+
+```
+cardano-cli shelley --help
+Up to date
+Usage: cardano-cli shelley COMMAND
+  Shelley specific commands
+
+Available options:
+  -h,--help                Show this help text
+
+Available commands:
+  address                  Shelley payment address commands
+  stake-address            Shelley stake address commands
+  key                      Shelley key utility commands
+  transaction              Shelley transaction commands
+  node                     Shelley node operaton commands
+  stake-pool               Shelley stake pool commands
+  query                    Shelley node query commands. Will query the local
+                           node whose Unix domain socket is obtained from the
+                           CARDANO_NODE_SOCKET_PATH enviromnent variable.
+  genesis                  Shelley genesis block commands
+  governance               Shelley governance commands
+  text-view                Commands for dealing with Shelley TextView files.
+                           Transactions, addresses etc are stored on disk as
+                           TextView files.
+
+
+```
+
+Byron-specific commands
+
+```
+cardano-cli byron --help
+Up to date
+Usage: cardano-cli byron (COMMAND | COMMAND | COMMAND | COMMAND | COMMAND | 
+                           COMMAND | COMMAND)
+  Byron specific commands
+
+Available options:
+  -h,--help                Show this help text
+
+Available commands:
+  key                      Byron key utility commands
+  transaction              Byron transaction commands
+  query                    Byron node query commands.
+  genesis                  Byron genesis block commands
+  governance               Byron governance commands
+  delegation               Byron delegation commands
+  miscellaneous            Byron miscellaneous commands
+```
 
 ## How to build