Merge bitcoin/bitcoin#29686: Update manpage descriptions

achow101 · achow101 · commit f842d0801e13 · 2024-11-08T13:34:59.000-05:00
47f50c7 doc: add bitcoin-qt man description (willcl-ark) 40b82e3 doc: add bitcoin-util man description (willcl-ark) a7bf80f doc: add bitcoin-tx man description (willcl-ark) 3f9a516 doc: add bitcoin-wallet man description (willcl-ark) d8c0bb2 doc: add bitcoin-cli man description (willcl-ark) 09abccf doc: add bitcoind man description (willcl-ark) Pull request description: Closes #29552 Add better descriptions to help string for all binaries. Use format which is correctly detected by help2man when generating manpages. Examples: Before: ![image](https://github.com/bitcoin/bitcoin/assets/6606587/9f6a5dbd-b18b-416b-827b-1c260d7a1274) After: ![image](https://github.com/bitcoin/bitcoin/assets/6606587/179082a1-1082-4204-bad7-56260d0fdefc) Demonstration using `bitcoin-cli` also highlights removal of inline usage explanations which were being incorrectly formatted by `help2man`. This results in the following changed format to `bitcoin-cli --help`: ![image](https://github.com/bitcoin/bitcoin/assets/6606587/dbebb99f-e419-40cd-a82d-e87f33351fea) ACKs for top commit: achow101: ACK 47f50c7 tdb3: re ACK 47f50c7 rkrux: tACK 47f50c7 maflcko: ACK 47f50c7 📠 Tree-SHA512: 124a8877077b7d47758ea970949d472b2444e3ba65d2bfeb47ebbdb1f5f8d3bf0abe2c88714bb6c92ba0e36583f0b36aa6f016ea88b65f011c610096ea872182
diff --git a/src/bitcoin-cli.cpp b/src/bitcoin-cli.cpp
@@ -152,10 +152,16 @@ static int AppInitRPC(int argc, char* argv[])
             strUsage += FormatParagraph(LicenseInfo());
         } else {
             strUsage += "\n"
-                "Usage:  bitcoin-cli [options] <command> [params]  Send command to " CLIENT_NAME "\n"
-                "or:     bitcoin-cli [options] -named <command> [name=value]...  Send command to " CLIENT_NAME " (with named arguments)\n"
-                "or:     bitcoin-cli [options] help                List commands\n"
-                "or:     bitcoin-cli [options] help <command>      Get help for a command\n";
+                "The bitcoin-cli utility provides a command line interface to interact with a " CLIENT_NAME " RPC server.\n"
+                "\nIt can be used to query network information, manage wallets, create or broadcast transactions, and control the " CLIENT_NAME " server.\n"
+                "\nUse the \"help\" command to list all commands. Use \"help <command>\" to show help for that command.\n"
+                "The -named option allows you to specify parameters using the key=value format, eliminating the need to pass unused positional parameters.\n"
+                "\n"
+                "Usage: bitcoin-cli [options] <command> [params]\n"
+                "or:    bitcoin-cli [options] -named <command> [name=value]...\n"
+                "or:    bitcoin-cli [options] help\n"
+                "or:    bitcoin-cli [options] help <command>\n"
+                "\n";
             strUsage += "\n" + gArgs.GetHelpMessage();
         }
 
diff --git a/src/bitcoin-tx.cpp b/src/bitcoin-tx.cpp
@@ -113,8 +113,11 @@ static int AppInitRawTx(int argc, char* argv[])
             strUsage += FormatParagraph(LicenseInfo());
         } else {
             strUsage += "\n"
-                "Usage:  bitcoin-tx [options] <hex-tx> [commands]  Update hex-encoded bitcoin transaction\n"
-                "or:     bitcoin-tx [options] -create [commands]   Create hex-encoded bitcoin transaction\n"
+                "The bitcoin-tx tool is used for creating and modifying bitcoin transactions.\n\n"
+                "bitcoin-tx can be used with \"<hex-tx> [commands]\" to update a hex-encoded bitcoin transaction, or with \"-create [commands]\" to create a hex-encoded bitcoin transaction.\n"
+                "\n"
+                "Usage: bitcoin-tx [options] <hex-tx> [commands]\n"
+                "or:    bitcoin-tx [options] -create [commands]\n"
                 "\n";
             strUsage += gArgs.GetHelpMessage();
         }
diff --git a/src/bitcoin-util.cpp b/src/bitcoin-util.cpp
@@ -58,7 +58,10 @@ static int AppInitUtil(ArgsManager& args, int argc, char* argv[])
             strUsage += FormatParagraph(LicenseInfo());
         } else {
             strUsage += "\n"
-                "Usage:  bitcoin-util [options] [commands]  Do stuff\n";
+                "The bitcoin-util tool provides bitcoin related functionality that does not rely on the ability to access a running node. Available [commands] are listed below.\n"
+                "\n"
+                "Usage:  bitcoin-util [options] [command]\n"
+                "or:     bitcoin-util [options] grind <hex-block-header>\n";
             strUsage += "\n" + args.GetHelpMessage();
         }
 
diff --git a/src/bitcoin-wallet.cpp b/src/bitcoin-wallet.cpp
@@ -61,17 +61,18 @@ static std::optional<int> WalletAppInit(ArgsManager& args, int argc, char* argv[
     }
     const bool missing_args{argc < 2};
     if (missing_args || HelpRequested(args) || args.IsArgSet("-version")) {
-        std::string strUsage = strprintf("%s bitcoin-wallet version", CLIENT_NAME) + " " + FormatFullVersion() + "\n";
+        std::string strUsage = strprintf("%s bitcoin-wallet utility version", CLIENT_NAME) + " " + FormatFullVersion() + "\n";
 
         if (args.IsArgSet("-version")) {
             strUsage += FormatParagraph(LicenseInfo());
         } else {
             strUsage += "\n"
-                        "bitcoin-wallet is an offline tool for creating and interacting with " CLIENT_NAME " wallet files.\n"
-                        "By default bitcoin-wallet will act on wallets in the default mainnet wallet directory in the datadir.\n"
-                        "To change the target wallet, use the -datadir, -wallet and -regtest/-signet/-testnet/-testnet4 arguments.\n\n"
-                        "Usage:\n"
-                        "  bitcoin-wallet [options] <command>\n";
+                "bitcoin-wallet is an offline tool for creating and interacting with " CLIENT_NAME " wallet files.\n\n"
+                "By default bitcoin-wallet will act on wallets in the default mainnet wallet directory in the datadir.\n\n"
+                "To change the target wallet, use the -datadir, -wallet and -regtest / -signet / -testnet arguments.\n"
+                "\n"
+                "Usage: bitcoin-wallet [options] <command>\n"
+                "\n";
             strUsage += "\n" + args.GetHelpMessage();
         }
         tfm::format(std::cout, "%s", strUsage);
diff --git a/src/bitcoind.cpp b/src/bitcoind.cpp
@@ -136,12 +136,18 @@ static bool ProcessInitCommands(ArgsManager& args)
 {
     // Process help and version before taking care about datadir
     if (HelpRequested(args) || args.IsArgSet("-version")) {
-        std::string strUsage = CLIENT_NAME " version " + FormatFullVersion() + "\n";
+        std::string strUsage = CLIENT_NAME " daemon version " + FormatFullVersion() + "\n";
 
         if (args.IsArgSet("-version")) {
             strUsage += FormatParagraph(LicenseInfo());
         } else {
-            strUsage += "\nUsage:  bitcoind [options]                     Start " CLIENT_NAME "\n"
+            strUsage += "\n"
+                "The " CLIENT_NAME " daemon (bitcoind) is a headless program that connects to the Bitcoin network to validate and relay transactions and blocks, as well as relaying addresses.\n\n"
+                "It provides the backbone of the Bitcoin network and its RPC, REST and ZMQ services can provide various transaction, block and address-related services.\n\n"
+                "There is an optional wallet component which provides transaction services.\n\n"
+                "It can be used in a headless environment or as part of a server setup.\n"
+                "\n"
+                "Usage: bitcoind [options]\n"
                 "\n";
             strUsage += args.GetHelpMessage();
         }
diff --git a/src/qt/utilitydialog.cpp b/src/qt/utilitydialog.cpp
@@ -56,8 +56,11 @@ HelpMessageDialog::HelpMessageDialog(QWidget *parent, bool about) :
         ui->helpMessage->setVisible(false);
     } else {
         setWindowTitle(tr("Command-line options"));
-        QString header = "Usage: bitcoin-qt [command-line options] [URI]\n\n"
-                         "Optional URI is a Bitcoin address in BIP21 URI format.\n";
+        QString header = "The bitcoin-qt application provides a graphical interface for interacting with " CLIENT_NAME ".\n\n"
+                         "It combines the core functionalities of bitcoind with a user-friendly interface for wallet management, transaction history, and network statistics.\n\n"
+                         "It is suitable for users who prefer a graphical over a command-line interface.\n\n"
+                         "You can optionally specify a payment [URI], in e.g. the BIP21 URI format.\n\n"
+                         "Usage: bitcoin-qt [options] [URI]\n\n";
         QTextCursor cursor(ui->helpMessage->document());
         cursor.insertText(version);
         cursor.insertBlock();
