From 4efda213e4026634173de4baa6024ec8caa60af7 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sun, 28 Apr 2024 04:01:50 +0200
Subject: [PATCH] New subcommand: help.

It's sometimes handy to just type e.g. "dss help run" to see the
synopsis and the options of the ls subcommand.
---
 dss.c        | 45 +++++++++++++++++++++++++++++++++++++++++----
 dss.suite.m4 | 18 +++++++++++++++++-
 2 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/dss.c b/dss.c
index 7a64346..477df6f 100644
--- a/dss.c
+++ b/dss.c
@@ -1834,15 +1834,18 @@ static void handle_version_and_help(void)
 {
 	char *txt;
 
+	if (OPT_GIVEN(DSS, VERSION)) {
+		printf("%s\n", dss_version());
+		exit(EXIT_SUCCESS);
+	}
 	if (OPT_GIVEN(DSS, DETAILED_HELP))
 		txt = lls_long_help(CMD_PTR(DSS));
 	else if (OPT_GIVEN(DSS, HELP))
 		txt = lls_short_help(CMD_PTR(DSS));
-	else if (OPT_GIVEN(DSS, VERSION))
-		txt = make_message("%s\n", dss_version());
 	else
 		return;
 	printf("%s", txt);
+	printf("\nRun dss help for help on subcommands.\n");
 	free(txt);
 	exit(EXIT_SUCCESS);
 }
@@ -1858,8 +1861,39 @@ static void show_subcommand_summary(void)
 		const char *purpose = lls_purpose(cmd);
 		printf("%-11s%s\n", name, purpose);
 	}
-	exit(EXIT_SUCCESS);
+	printf("\nRun dss help <subcmd> for help on <subcmd>.\n");
+}
+
+static int com_help(void)
+{
+	int ret;
+	char *errctx, *help;
+	const char *arg;
+	const struct lls_command *cmd;
+
+	ret = lls_check_arg_count(sublpr, 0, 1, &errctx);
+	if (ret < 0)
+		return lopsub_error(ret, &errctx);
+	if (lls_num_inputs(sublpr) == 0) {
+		show_subcommand_summary();
+		return 0;
+	}
+	arg = lls_input(0, sublpr);
+	ret = lls_lookup_subcmd(arg, dss_suite, &errctx);
+	if (ret < 0)
+		return lopsub_error(ret, &errctx);
+	cmd = lls_cmd(ret, dss_suite);
+	if (OPT_GIVEN(HELP, LONG))
+		help = lls_long_help(cmd);
+	else
+		help = lls_short_help(cmd);
+	printf("%s", help);
+	free(help);
+	if (!OPT_GIVEN(HELP, LONG))
+		printf("\nRun dss -- help -l %s for long help.\n", arg);
+	return 0;
 }
+EXPORT_CMD_HANDLER(help);
 
 int main(int argc, char **argv)
 {
@@ -1880,8 +1914,11 @@ int main(int argc, char **argv)
 		goto out;
 	handle_version_and_help();
 	num_inputs = lls_num_inputs(lpr);
-	if (num_inputs == 0)
+	if (num_inputs == 0) {
 		show_subcommand_summary();
+		ret = 0;
+		goto out;
+	}
 	ret = lls_lookup_subcmd(argv[argc - num_inputs], dss_suite, &errctx);
 	if (ret < 0) {
 		ret = lopsub_error(ret, &errctx);
diff --git a/dss.suite.m4 b/dss.suite.m4
index 27437f4..3fe3122 100644
--- a/dss.suite.m4
+++ b/dss.suite.m4
@@ -526,9 +526,25 @@ caption = Subcommands
 		exits successfully or prints information about the first syntax error
 		detected and terminates with exit code 1.
 	[/description]
+[subcommand help]
+	purpose = list available subcommands or print subcommand-specific help
+	non-opts-name = [subcommand]
+	[description]
+		If the optional subcommand argument is given, the help text of that
+		subcommand is shown. Without the argument the available subcommands
+		are listed instead.
+	[/description]
+	[option long]
+		short_opt = l
+		summary = show the long help text of a subcommand
+		[help]
+			If this option is given, the command also shows the description of
+			the subcommand and the help text of each option, Otherwise only the
+			purpose, the synopsis and the option list of the subcommand is shown.
+			If no subcommand is supplied, the option has no effect.
+		[/help]
 
 [section examples]
-
 	Suppose you'd like to create snapshots of the existing directory
 	.I /foo/bar
 	in the directory
-- 
2.39.5