From d82d90d2bf7a9e684ab3ee9ccfcebce4772ba11b Mon Sep 17 00:00:00 2001
From: qflen <nkimon00@gmail.com>
Date: Tue, 21 Apr 2026 21:38:03 +0200
Subject: [PATCH] Display command aliases in generated man-pages

Subcommand aliases already surface in --help and dump-help, but the
generate-manual tool ignored CommandInfoV0.aliases. Single-page output
now lists aliases inline with the subcommand name (e.g. "multiply, mul"),
matching the --help format. Multi-page output lists aliases as
comma-separated .Nm entries in the NAME section, following the BSD mdoc
convention (see ls(1)).

Resolves #851.
---
 .../Snapshots/testMathMultiPageManual().mdoc           |  6 ++++--
 .../Snapshots/testMathSinglePageManual().mdoc          |  4 ++--
 Tools/generate-manual/DSL/Name.swift                   | 10 +++++++++-
 Tools/generate-manual/DSL/SinglePageDescription.swift  |  3 ++-
 .../Extensions/ArgumentParser+MDoc.swift               |  5 +++++
 5 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc
index 99288bd7f..9ea160e4e 100644
--- a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc
+++ b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc
@@ -77,7 +77,8 @@ and
 .Dt MATH.MULTIPLY 9
 .Os
 .Sh NAME
-.Nm "math multiply"
+.Nm "math multiply" ,
+.Nm mul
 .Nd "Print the product of the values."
 .Sh SYNOPSIS
 .Nm
@@ -150,7 +151,8 @@ and
 .Dt MATH.STATS.AVERAGE 9
 .Os
 .Sh NAME
-.Nm "math stats average"
+.Nm "math stats average" ,
+.Nm avg
 .Nd "Print the average of the values."
 .Sh SYNOPSIS
 .Nm
diff --git a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc
index 1aa384530..8a5c64de7 100644
--- a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc
+++ b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc
@@ -28,7 +28,7 @@ Show the version.
 .It Fl h , -help
 Show help information.
 .El
-.It Em multiply
+.It Em "multiply, mul"
 Print the product of the values.
 .Bl -tag -width 6n
 .It Fl x , -hex-output
@@ -47,7 +47,7 @@ Calculate descriptive statistics.
 Show the version.
 .It Fl h , -help
 Show help information.
-.It Em average
+.It Em "average, avg"
 Print the average of the values.
 .Bl -tag -width 6n
 .It Fl -kind Ar kind
diff --git a/Tools/generate-manual/DSL/Name.swift b/Tools/generate-manual/DSL/Name.swift
index 3d6711383..a584615aa 100644
--- a/Tools/generate-manual/DSL/Name.swift
+++ b/Tools/generate-manual/DSL/Name.swift
@@ -16,8 +16,16 @@ struct Name: MDocComponent {
   var command: CommandInfoV0
 
   var body: MDocComponent {
+    let names = [command.manualPageName] + (command.aliases ?? [])
     Section(title: "name") {
-      MDocMacro.DocumentName(name: command.manualPageName)
+      for (index, name) in names.enumerated() {
+        if index < names.count - 1 {
+          MDocMacro.DocumentName(name: name)
+            .withUnsafeChildren(nodes: [","])
+        } else {
+          MDocMacro.DocumentName(name: name)
+        }
+      }
       if let abstract = command.abstract {
         MDocMacro.DocumentDescription(description: abstract)
       }
diff --git a/Tools/generate-manual/DSL/SinglePageDescription.swift b/Tools/generate-manual/DSL/SinglePageDescription.swift
index 62f95d8fe..1c30d3f9e 100644
--- a/Tools/generate-manual/DSL/SinglePageDescription.swift
+++ b/Tools/generate-manual/DSL/SinglePageDescription.swift
@@ -67,7 +67,8 @@ struct SinglePageDescription: MDocComponent {
 
       for subcommand in command.subcommands ?? [] {
         MDocMacro.ListItem(
-          title: MDocMacro.Emphasis(arguments: [subcommand.commandName]))
+          title: MDocMacro.Emphasis(
+            arguments: [subcommand.manualPageSubcommandLabel]))
         SinglePageDescription(command: subcommand, root: false).core
       }
     }
diff --git a/Tools/generate-manual/Extensions/ArgumentParser+MDoc.swift b/Tools/generate-manual/Extensions/ArgumentParser+MDoc.swift
index 0999d9148..b1e682ecc 100644
--- a/Tools/generate-manual/Extensions/ArgumentParser+MDoc.swift
+++ b/Tools/generate-manual/Extensions/ArgumentParser+MDoc.swift
@@ -31,6 +31,11 @@ extension CommandInfoV0 {
     let parts = (superCommands ?? []) + [commandName]
     return parts.joined(separator: " ")
   }
+
+  var manualPageSubcommandLabel: String {
+    guard let aliases = aliases, !aliases.isEmpty else { return commandName }
+    return ([commandName] + aliases).joined(separator: ", ")
+  }
 }
 
 extension ArgumentInfoV0 {