Add subcommand abstracts to single-page manuals (#552)

- 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.

Author: rauhul

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

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 {

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
       }
     }
   }