SOLR-18515: Preserve hyphenated picocli command names in generated CLI docs

solr/solr-ref-guide/build.gradle

@@ -609,16 +609,28 @@ def DO_NOT_EDIT_NOTICE = """\
 """
 
 // Convert a generated filename stem (e.g. "solr-zk-ls") to an Antora page title
-// e.g. "solr-zk-ls" -> "bin/solr zk ls"
-String cliFileNameToTitle(String baseName) {
-  def parts = baseName.split('-')
-  return "bin/solr " + parts.drop(1).join(' ')
-}
-
-// Return the short nav label for a command file (last segment of dash-separated name)
-// e.g. "solr-zk-ls" -> "ls"
-String cliFileNameToNavLabel(String baseName) {
-  return baseName.split('-').last()
+// A dash separated commands only when that prefix is itself a generated page,
+// so a hyphen inside the leaf name is kept
+// e.g. "solr-zk-ls" -> "bin/solr zk ls". "solr-package-add-key" -> "bin/solr package add-key"
+String cliFileNameToTitle(String baseName, Set stems) {
+  return "bin/solr " + cliCommandPath(baseName, stems).join(' ')
+}
+
+// Tokens of the title after "solr". That last token is the nav label.
+// e.g. "solr-zk-ls" -> [zk, ls], "solr-package-add-key" -> [package, add-key]
+List<String> cliCommandPath(String baseName, Set stems) {
+  def cuts = [baseName.indexOf('-')]
+  for (def i = baseName.indexOf('-', cuts[0] + 1); i >= 0; i = baseName.indexOf('-', i + 1)) {
+    if (stems.contains(baseName.substring(0, i))) {
+      cuts.add(i)
+    }
+  }
+  cuts.add(baseName.length())
+  def segments = []
+  for (def c = 0; c < cuts.size() - 1; c++) {
+    segments.add(baseName.substring(cuts[c] + 1, cuts[c + 1]))
+  }
+  return segments
 }
 
 // Strip "[...]" (optional groups) and "(...)" (required groups whose members
@@ -707,10 +719,10 @@ String markRequiredOptionsAndArgs(String content) {
 // Post-process a raw ManPageGenerator AsciiDoc file for Antora compatibility.
 // The title lives inside the man-section-header block, so we replace the whole
 // header block with an Antora-compatible page title + attributes.
-String postProcessCliManPage(File rawFile, String asfHeader, String doNotEditNotice, String experimentalNotice) {
+String postProcessCliManPage(File rawFile, Set stems, String asfHeader, String doNotEditNotice, String experimentalNotice) {
   def content = rawFile.text
   def baseName = rawFile.name.replace('.adoc', '')
-  def newTitle = cliFileNameToTitle(baseName)
+  def newTitle = cliFileNameToTitle(baseName, stems)
 
   // Replace the entire man-section-header block (which contains :doctype:manpage, the page title
   // "= solr-start(1)", etc.) with our Antora-compatible title and page attributes.
@@ -776,9 +788,10 @@ String buildCliCommandTable(File cliDir) {
   def files = ((cliDir.listFiles() ?: []) as List<File>)
     .findAll { it.name.startsWith('solr-') && it.name.endsWith('.adoc') }
     .sort { it.name }
+  def stems = files.collect { it.name.replace('.adoc', '') } as Set
   def rows = files.collect { file ->
     def baseName = file.name.replace('.adoc', '')
-    "|xref:cli/${file.name}[${cliFileNameToTitle(baseName)}]"
+    "|xref:cli/${file.name}[${cliFileNameToTitle(baseName, stems)}]"
   }
   return "[cols=\"1\",options=\"header\"]\n|===\n|Command\n\n" + rows.join('\n') + "\n|==="
 }
@@ -792,18 +805,9 @@ List<String> buildCliNavEntries(File cliDir) {
     .sort { (it.name.replace('.adoc', '') + '\u0000') }
   def stems = files.collect { it.name.replace('.adoc', '') } as Set
   return files.collect { file ->
-    def baseName = file.name.replace('.adoc', '')
-    def label = cliFileNameToNavLabel(baseName)
-    // Nest under the deepest ancestor that is itself a generated page. Counting dashes instead
-    // would mis-nest a command whose own name contains one, e.g. a future "snapshot-create"
-    // would be filed under a "solr-snapshot" page that does not exist.
-    def depth = 0
-    for (def stem = baseName; stem.contains('-'); ) {
-      stem = stem.substring(0, stem.lastIndexOf('-'))
-      if (stems.contains(stem)) {
-        depth++
-      }
-    }
+    def path = cliCommandPath(file.name.replace('.adoc', ''), stems)
+    def label = path.last()
+    def depth = path.size() - 1
     // Generated pages hang off cli/index.adoc, which itself sits under the control script page,
     // so the shallowest generated page is already three levels deep.
     def stars = '*' * (depth + 3)
@@ -855,9 +859,10 @@ task generateCliDocs {
     destDir.mkdirs()
 
     def rawFiles = runManPageGenerator(rawOutputDir)
+    def stems = rawFiles.collect { it.name.replace('.adoc', '') } as Set
 
     rawFiles.each { rawFile ->
-      def processed = postProcessCliManPage(rawFile, ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
+      def processed = postProcessCliManPage(rawFile, stems, ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
       new File(destDir, rawFile.name).text = processed
     }
 
@@ -910,10 +915,11 @@ task checkCliDocsUpToDate {
     rawOutputDir.mkdirs()
 
     def rawFiles = runManPageGenerator(rawOutputDir)
+    def stems = rawFiles.collect { it.name.replace('.adoc', '') } as Set
     def issues = []
 
     rawFiles.each { rawFile ->
-      def processed = postProcessCliManPage(rawFile, ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
+      def processed = postProcessCliManPage(rawFile, stems, ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
       def committed = new File(committedDir, rawFile.name)
       if (!committed.exists()) {
         issues << "MISSING committed file (new command): ${rawFile.name}"

solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc

@@ -30,13 +30,13 @@
 *** xref:cli/solr-export.adoc[export]
 *** xref:cli/solr-healthcheck.adoc[healthcheck]
 *** xref:cli/solr-package.adoc[package]
-**** xref:cli/solr-package-add-key.adoc[key]
-**** xref:cli/solr-package-add-repo.adoc[repo]
+**** xref:cli/solr-package-add-key.adoc[add-key]
+**** xref:cli/solr-package-add-repo.adoc[add-repo]
 **** xref:cli/solr-package-deploy.adoc[deploy]
 **** xref:cli/solr-package-install.adoc[install]
-**** xref:cli/solr-package-list-available.adoc[available]
-**** xref:cli/solr-package-list-deployed.adoc[deployed]
-**** xref:cli/solr-package-list-installed.adoc[installed]
+**** xref:cli/solr-package-list-available.adoc[list-available]
+**** xref:cli/solr-package-list-deployed.adoc[list-deployed]
+**** xref:cli/solr-package-list-installed.adoc[list-installed]
 **** xref:cli/solr-package-undeploy.adoc[undeploy]
 **** xref:cli/solr-package-uninstall.adoc[uninstall]
 *** xref:cli/solr-post.adoc[post]

solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc

@@ -68,13 +68,13 @@ Any command not listed here is unavailable when the picocli implementation is en
 |xref:cli/solr-delete.adoc[bin/solr delete]
 |xref:cli/solr-export.adoc[bin/solr export]
 |xref:cli/solr-healthcheck.adoc[bin/solr healthcheck]
-|xref:cli/solr-package-add-key.adoc[bin/solr package add key]
-|xref:cli/solr-package-add-repo.adoc[bin/solr package add repo]
+|xref:cli/solr-package-add-key.adoc[bin/solr package add-key]
+|xref:cli/solr-package-add-repo.adoc[bin/solr package add-repo]
 |xref:cli/solr-package-deploy.adoc[bin/solr package deploy]
 |xref:cli/solr-package-install.adoc[bin/solr package install]
-|xref:cli/solr-package-list-available.adoc[bin/solr package list available]
-|xref:cli/solr-package-list-deployed.adoc[bin/solr package list deployed]
-|xref:cli/solr-package-list-installed.adoc[bin/solr package list installed]
+|xref:cli/solr-package-list-available.adoc[bin/solr package list-available]
+|xref:cli/solr-package-list-deployed.adoc[bin/solr package list-deployed]
+|xref:cli/solr-package-list-installed.adoc[bin/solr package list-installed]
 |xref:cli/solr-package-undeploy.adoc[bin/solr package undeploy]
 |xref:cli/solr-package-uninstall.adoc[bin/solr package uninstall]
 |xref:cli/solr-package.adoc[bin/solr package]

solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-key.adoc

@@ -19,7 +19,7 @@
 // To update: modify the @Command/@Option annotations in the Java source, then run:
 //   ./gradlew :solr:solr-ref-guide:generateCliDocs
 
-= bin/solr package add key
+= bin/solr package add-key
 :page-toclevels: 2
 
 [WARNING]

solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-repo.adoc

@@ -19,7 +19,7 @@
 // To update: modify the @Command/@Option annotations in the Java source, then run:
 //   ./gradlew :solr:solr-ref-guide:generateCliDocs
 
-= bin/solr package add repo
+= bin/solr package add-repo
 :page-toclevels: 2
 
 [WARNING]

solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-available.adoc

@@ -19,7 +19,7 @@
 // To update: modify the @Command/@Option annotations in the Java source, then run:
 //   ./gradlew :solr:solr-ref-guide:generateCliDocs
 
-= bin/solr package list available
+= bin/solr package list-available
 :page-toclevels: 2
 
 [WARNING]

solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-deployed.adoc

@@ -19,7 +19,7 @@
 // To update: modify the @Command/@Option annotations in the Java source, then run:
 //   ./gradlew :solr:solr-ref-guide:generateCliDocs
 
-= bin/solr package list deployed
+= bin/solr package list-deployed
 :page-toclevels: 2
 
 [WARNING]

solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-installed.adoc

@@ -19,7 +19,7 @@
 // To update: modify the @Command/@Option annotations in the Java source, then run:
 //   ./gradlew :solr:solr-ref-guide:generateCliDocs
 
-= bin/solr package list installed
+= bin/solr package list-installed
 :page-toclevels: 2
 
 [WARNING]