Repository: apple/swift-argument-parser (swift)

Issue:
Manual Generation: Abstracts for subcommands missing in single page mode
When I run swift package plugin generate-manual in the default single page mode, I was expecting that the resulting man page would include the abstract of the sub commands. The multi-page mode includes these in the different pages as expected. Without it, the help just has the sub command name and all it's flags (including the description for the flags) - but it doesn't help you in understanding when to use which subcommand.

**ArgumentParser version:** 1.2.2
**Swift version:** 5.7.2

### Checklist
- [x] If possible, I've reproduced the issue using the `main` branch of this package
- [x] I've searched for [existing GitHub issues](https://github.com/apple/swift-argument-parser/issues)

### Steps to Reproduce
`swift package plugin generate-manual`

### Expected behavior
Example output for a check sub-command:

```
.It Em check
Parses a ledger and prints any errors it finds
.Bl -tag -width 6n
.It Ar file
The file to parse.
.It Fl q , -quiet
Don't print errors, only indicate via exit code.
```

### Actual behavior
Example output for a check sub-command:

```
.It Em check
.Bl -tag -width 6n
.It Ar file
The file to parse.
.It Fl q , -quiet
Don't print errors, only indicate via exit code.

Pull request:
Fixes #551

- Fixes a bug where signle-page manuals did not include subcommand abstracts because the DSL logic did not take to account root commands vs subcommands. This change adds a "root" property to the DSL element to allow for styling differences in the two cases.

Thanks @Nef10 for reporting this issue. If you have time could you try this branch and verify it solves the issue in your project.

Patch:
diff --git a/Tools/generate-manual/DSL/Document.swift b/Tools/generate-manual/DSL/Document.swift
index fe80d42e7..86c43aed0 100644
--- a/Tools/generate-manual/DSL/Document.swift
+++ b/Tools/generate-manual/DSL/Document.swift
@@ -27,7 +27,7 @@ struct Document: MDocComponent {
     if multiPage {
       MultiPageDescription(command: command)
     } else {
-      SinglePageDescription(command: command)
+      SinglePageDescription(command: command, root: true)
     }
     Exit(section: section)
     if multiPage {
diff --git a/Tools/generate-manual/DSL/SinglePageDescription.swift b/Tools/generate-manual/DSL/SinglePageDescription.swift
index dbbe947a2..01b0b2e99 100644
--- a/Tools/generate-manual/DSL/SinglePageDescription.swift
+++ b/Tools/generate-manual/DSL/SinglePageDescription.swift
@@ -14,6 +14,7 @@ import ArgumentParserToolInfo
 
 struct SinglePageDescription: MDocComponent {
   var command: CommandInfoV0
+  var root: Bool
 
   var body: MDocComponent {
     Section(title: "description") {
@@ -23,6 +24,14 @@ struct SinglePageDescription: MDocComponent {
 
   @MDocBuilder
   var core: MDocComponent {
+    if !root, let abstract = command.abstract {
+      abstract
+    }
+
+    if !root, command.abstract != nil, command.discussion != nil {
+      MDocMacro.ParagraphBreak()
+    }
+
     if let discussion = command.discussion {
       discussion
     }
@@ -46,7 +55,7 @@ struct SinglePageDescription: MDocComponent {
 
       for subcommand in command.subcommands ?? [] {
         MDocMacro.ListItem(title: MDocMacro.Emphasis(arguments: [subcommand.commandName]))
-        SinglePageDescription(command: subcommand).core
+        SinglePageDescription(command: subcommand, root: false).core
       }
     }
   }


Test patch:
diff --git a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift
index 23c332215..ad7ffc20d 100644
--- a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift
+++ b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift
@@ -35,6 +35,7 @@ final class MathGenerateManualTests: XCTestCase {
       .It Fl h , -help
       Show help information.
       .It Em add
+      Print the sum of the values.
       .Bl -tag -width 6n
       .It Fl x , -hex-output
       Use hexadecimal notation for the result.
@@ -46,6 +47,7 @@ final class MathGenerateManualTests: XCTestCase {
       Show help information.
       .El
       .It Em multiply
+      Print the product of the values.
       .Bl -tag -width 6n
       .It Fl x , -hex-output
       Use hexadecimal notation for the result.
@@ -57,12 +59,14 @@ final class MathGenerateManualTests: XCTestCase {
       Show help information.
       .El
       .It Em stats
+      Calculate descriptive statistics.
       .Bl -tag -width 6n
       .It Fl -version
       Show the version.
       .It Fl h , -help
       Show help information.
       .It Em average
+      Print the average of the values.
       .Bl -tag -width 6n
       .It Fl -kind Ar kind
       The kind of average to provide.
@@ -74,6 +78,7 @@ final class MathGenerateManualTests: XCTestCase {
       Show help information.
       .El
       .It Em stdev
+      Print the standard deviation of the values.
       .Bl -tag -width 6n
       .It Ar values...
       A group of floating-point values to operate on.
@@ -83,6 +88,7 @@ final class MathGenerateManualTests: XCTestCase {
       Show help information.
       .El
       .It Em quantiles
+      Print the quantiles of the values (TBD).
       .Bl -tag -width 6n
       .It Ar one-of-four
       .It Ar custom-arg