Merge pull request dita-ot#4549 from dita-ot/feature/cli-help

Add help subcommand

src/main/java/org/dita/dost/invoker/ArgumentParser.java

@@ -89,6 +89,8 @@ static synchronized Map<String, Arguments.Argument> getPluginArguments() {
   public Arguments processArgs(final String[] arguments) {
     for (final String subcommand : arguments) {
       switch (getName(subcommand)) {
+        case "help":
+          return new HelpArguments().parse(arguments);
         case "plugins":
           return new PluginsArguments().parse(arguments);
         case "version":

src/main/java/org/dita/dost/invoker/HelpArguments.java

@@ -0,0 +1,70 @@
+/*
+ * This file is part of the DITA Open Toolkit project.
+ *
+ * Copyright 2024 Jarno Elovirta
+ *
+ * See the accompanying LICENSE file for applicable license.
+ */
+
+package org.dita.dost.invoker;
+
+import java.util.ArrayDeque;
+import java.util.Arrays;
+import java.util.Deque;
+import org.apache.tools.ant.Project;
+
+/**
+ * Help subcommand is intended to serve as a fallback to --help option. It should not be documented as
+ * a subcommand, but instead it's a recovery when user without prior knowledge guesses that help can be
+ * accessed with the help subcommand.
+ */
+public class HelpArguments extends Arguments {
+
+  String subcommand;
+
+  @Override
+  HelpArguments parse(final String[] arguments) {
+    final Deque<String> args = new ArrayDeque<>(Arrays.asList(arguments));
+    while (!args.isEmpty()) {
+      final String arg = args.pop();
+      if (arg.equals("help")) {
+        break;
+      } else if (arg.startsWith("-")) {
+        parseCommonOptions(arg, args);
+      } else {
+        subcommand = arg;
+      }
+    }
+    while (!args.isEmpty()) {
+      final String arg = args.pop();
+      if (arg.startsWith("-")) {
+        parseCommonOptions(arg, args);
+      } else {
+        subcommand = arg;
+      }
+    }
+    if (msgOutputLevel < Project.MSG_INFO) {
+      emacsMode = true;
+    }
+    justPrintUsage = true;
+
+    return this;
+  }
+
+  @Override
+  String getUsage(final boolean compact) {
+    if (subcommand == null) {
+      return new ConversionArguments().getUsage(false);
+    }
+    return switch (subcommand) {
+      case "plugins" -> new PluginsArguments().getUsage(false);
+      case "version" -> new VersionArguments().getUsage(false);
+      case "transtypes" -> new TranstypesArguments().getUsage(false);
+      case "deliverables" -> new DeliverablesArguments().getUsage(false);
+      case "install" -> new InstallArguments().getUsage(false);
+      case "uninstall" -> new UninstallArguments().getUsage(false);
+      case "init" -> new InitArguments().getUsage(false);
+      default -> new ConversionArguments().getUsage(false);
+    };
+  }
+}

src/main/java/org/dita/dost/invoker/InitArguments.java

@@ -81,6 +81,7 @@ String getUsage(final boolean compact) {
     return UsageBuilder
       .builder(compact, useColor)
       .usage(locale.getString("init.usage"))
+      .usage(locale.getString("init.usage.list"))
       .arguments(null, null, "template", locale.getString("init.argument.template"))
       .options("o", "output", "dir", locale.getString("init.option.output"))
       .options(null, "list", null, locale.getString("init.option.list"))

src/main/java/org/dita/dost/invoker/Main.java

@@ -567,14 +567,16 @@ private void printInitList() {
       .filter(entry -> Objects.nonNull(entry.getKey()))
       .sorted(Map.Entry.comparingByKey())
       .toList();
-    var width = templates
-      .stream()
-      .map(stringStringEntry -> stringStringEntry.getKey().length())
-      .max(Integer::compare)
-      .get();
-    templates.forEach(dir ->
-      logger.info(dir.getKey() + " ".repeat(width - dir.getKey().length()) + "  " + dir.getValue())
-    );
+    if (!templates.isEmpty()) {
+      var width = templates
+        .stream()
+        .map(stringStringEntry -> stringStringEntry.getKey().length())
+        .max(Integer::compare)
+        .get();
+      templates.forEach(dir ->
+        logger.info(dir.getKey() + " ".repeat(width - dir.getKey().length()) + "  " + dir.getValue())
+      );
+    }
   }
 
   private void install(InstallArguments installArgs) {

src/main/resources/cli_en_US.properties

@@ -42,6 +42,7 @@ uninstall.error.plugin_not_found=Plug-in %s not found
 transtypes.usage=dita transtypes [options]
 # Init subcommand
 init.usage=dita init <template> [options]
+init.usage.list=dita init --list [options]
 init.argument.template=Template name
 init.option.output=Output directory
 init.option.list=List installed templates