btrfs-progs: update help texts to better explain global options

There was a question in the mailing list regarding option --quiet and
why it's not working as 'btrfs subvolume create --quiet ...'.
Historically there were per-command verbosity options but this was
unified under the global options with it's specific syntax. This is not
uncommon and e.g. git also does have this option split.

The documentation and help strings are not making this clear enough, so
print syntax examples at the end of the help of 'btrfs', and do other
adjustments.

Signed-off-by: David Sterba <dsterba@suse.com>

Author: kdave

Documentation/btrfs.rst

@@ -4,7 +4,7 @@ btrfs(8)
 SYNOPSIS
 --------
 
-**btrfs** [global] <group> [<group>...] <command> [<args>]
+**btrfs** [global options] <group> [<group>...] <command> [options] [<args>]
 
 DESCRIPTION
 -----------
@@ -43,11 +43,17 @@ All numbers will be formatted according to the rules of the `C` locale
 (ignoring the shell locale, see :manref:`locale(7)`).
 
 For an overview of a given command use :command:`btrfs command --help`
-or :command:`btrfs [command...] --help --full` to print all available options.
+or :command:`btrfs [command...] help --full` to print all available options
+for all commands.
 
 There are global options that are passed between *btrfs* and the *group* name
 and affect behaviour not specific to the command, e.g. verbosity or the type
-of the output.
+of the output:
+
+.. code-block:: bash
+
+        btrfs -q subvolume create ...
+        btrfs --dry-run subvolume create ...
 
 --format <format>
         if supported by the command, print subcommand output in that format (text, json)

btrfs.c

@@ -37,7 +37,7 @@ static const char * const btrfs_cmd_group_usage[] = {
 	 * The main command group is the only one that takes options so this
 	 * needs the newlines and manual formatting.
 	 */
-	"btrfs [global] <group> [<group>...] <command> [<args>]\n"
+	"btrfs [global options] <group> [<group>...] <command> [options] [<args>]\n"
 	"\n"
 	"Global options:\n"
 	"  --format <format> if supported, print subcommand output in that format (text, json)\n"
@@ -48,12 +48,19 @@ static const char * const btrfs_cmd_group_usage[] = {
 	"\n"
 	"Options for the main command only:\n"
 	"  --help            print condensed help for all subcommands\n"
-	"  --version         print version string",
+	"  --version         print version string and built-in features",
 	NULL
 };
 
 static const char btrfs_cmd_group_info[] =
-	"Use --help as an argument for information on a specific group or command.";
+	"Use --help as an option for information about a group or command:\n"
+	"  btrfs subvolume --help\n"
+	"  btrfs subvolume create --help\n"
+	"\n"
+	"Global options like -q/-v must follow the tool name 'btrfs':\n"
+	"  btrfs -q subvolume create ...\n"
+	"  btrfs --dry-run subvolume create ..."
+	;
 
 static inline const char *skip_prefix(const char *str, const char *prefix)
 {
@@ -363,7 +370,6 @@ static void handle_special_globals(int shift, int argc, char **argv)
 			usage_command_group(&btrfs_cmd_group, true, false);
 		else
 			cmd_execute(&cmd_struct_help, argc, argv);
-		print_output_formats(stdout);
 		exit(0);
 	}