cli: generate man pages dynamically from command tree

Add dynamic man page generation by traversing the libecoli command
tree at runtime. Add new option in grcli (--man and --man [COMMAND])
to walk through the registered command nodes and extract required
data to generate properly formatted man pages in Markdown format.

Do build system changes in meson to invoke grcli --man during the
build phase. Convert the man pages in Markdown to groff format using
go-md2man.

Do changes for packaging files for both Debian and RPM

Assisted-by: Cursor/Claude-4-Sonnet
Signed-off-by: Abhiram R N <[email protected]>

Author: abhiramnarayana

cli/complete.c

@@ -14,24 +14,33 @@
 #define FLAG(flags, help) with_help(help, EC_NODE_CMD(EC_NO_ID, flags))
 #define OPT(opts, help, ...) with_help(help, EC_NODE_CMD(EC_NO_ID, opts, __VA_ARGS__))
 
+struct ec_node *grcli_options_node(void) {
+	return EC_NODE_SUBSET(
+		EC_NO_ID,
+		FLAG("-h|--help", "Show usage help and exit."),
+		OPT("-s|--socket " SOCK_PATH_ID,
+		    "Path to the control plane API socket.",
+		    ec_node("file", SOCK_PATH_ID)),
+		FLAG("-e|--err-exit", "Abort on first error."),
+		FLAG("-x|--trace-commands", "Print executed commands."),
+		OPT("-f|--file PATH",
+		    "Read commands from _PATH_ instead of standard input.",
+		    ec_node("file", "PATH")),
+		FLAG("-V|--version", "Print version and exit."),
+		FLAG("-c|--bash-complete", "For use in bash completion."),
+		OPT("-m|--man COMMAND",
+		    "Show man page for _COMMAND_ or list all commands if no argument.",
+		    ec_node("str", "COMMAND"))
+	);
+}
+
 static struct ec_node *bash_complete_node(struct ec_node *cmdlist) {
 	return ec_node_sh_lex_expand(
 		EC_NO_ID,
 		EC_NODE_SEQ(
 			EC_NO_ID,
 			ec_node("any", "prog_name"),
-			ec_node_option(
-				EC_NO_ID,
-				EC_NODE_SUBSET(
-					EC_NO_ID,
-					FLAG("-h|--help", "Show usage help and exit."),
-					OPT("-s|--socket " SOCK_PATH_ID,
-					    "Path to the control plane API socket.",
-					    ec_node("file", SOCK_PATH_ID)),
-					FLAG("-e|--err-exit", "Abort on first error."),
-					FLAG("-x|--trace-commands", "Print executed commands.")
-				)
-			),
+			ec_node_option(EC_NO_ID, grcli_options_node()),
 			cmdlist
 		)
 	);

cli/complete.h

@@ -6,3 +6,4 @@
 #include <ecoli.h>
 
 int bash_complete(struct ec_node *cmdlist);
+struct ec_node *grcli_options_node(void);

cli/main.c

@@ -5,6 +5,7 @@
 #include "exec.h"
 #include "interact.h"
 #include "log.h"
+#include "man.h"
 
 #include <gr_api.h>
 #include <gr_api_client_impl.h>
@@ -27,6 +28,7 @@
 static void usage(const char *prog) {
 	printf("Usage: %s [-e] [-f PATH] [-h] [-s PATH] [-V] [-x] ...\n", prog);
 	printf("       %s -c|--bash-complete\n", prog);
+	printf("       %s -m|--man [COMMAND]\n", prog);
 }
 
 static void help(void) {
@@ -37,6 +39,8 @@ static void help(void) {
 	puts("  -e, --err-exit             Abort on first error.");
 	puts("  -f PATH, --file PATH       Read commands from file instead of stdin.");
 	puts("  -h, --help                 Show this help message and exit.");
+	puts("  -m, --man [COMMAND]        Show man page for command or list all");
+	puts("                             commands.");
 	puts("  -s PATH, --socket PATH     Path to the control plane API socket.");
 	puts("                             Default: GROUT_SOCK_PATH from env or");
 	printf("                             %s).\n", GR_DEFAULT_SOCK_PATH);
@@ -171,8 +175,20 @@ int main(int argc, char **argv) {
 	if ((cmdlist = init_commands()) == NULL)
 		goto end;
 
-	if (argc >= 2 && (!strcmp(argv[1], "-c") || !strcmp(argv[1], "--bash-complete")))
-		return bash_complete(cmdlist);
+	if (argc >= 2 && (!strcmp(argv[1], "-c") || !strcmp(argv[1], "--bash-complete"))) {
+		ret = bash_complete(cmdlist);
+		goto end;
+	}
+
+	if (argc >= 2 && (!strcmp(argv[1], "-m") || !strcmp(argv[1], "--man"))) {
+		if (argc == 2) {
+			print_main_man_page(cmdlist);
+			ret = EXIT_SUCCESS;
+		} else {
+			ret = print_man_page(cmdlist, argc, argv);
+		}
+		goto end;
+	}
 
 	if ((c = parse_args(argc, argv)) < 0)
 		goto end;

cli/man.h

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Copyright (c) 2025 Robin Jarry
+
+#pragma once
+
+#include <ecoli.h>
+
+int print_man_page(struct ec_node *cmdlist, int argc, char **argv);
+void print_main_man_page(struct ec_node *cmdlist);