Add change log entry

Author: philderbeast

changelog.d/12221.md

@@ -0,0 +1,47 @@
+---
+synopsis: Command option help \# herald
+packages: [Cabal]
+prs: 12221
+issues: 1220
+---
+
+When laying out the table of options, `Distribution.GetOpt.usageInfo` marks the
+first line of each help description with a preceding `#` to herald the
+description. Longer descriptions wrap and this herald helps to itemize or
+separate descriptions, like bullet points in a list.
+
+The options may overflow the columns reserved for them. If they do the
+description of that option starts at its normal column but on the next line
+down. This leads to these combinations;
+
+- short option, short description,
+
+    ```pre
+    -h, --help                   # Show this help text.
+    ```
+
+- short option, long description,
+
+    ```pre
+    --enable-tests               # Enable dependency checking and compilation for
+                                   test suites listed in the package description
+                                   file.
+    ```
+
+- long option, short description,
+
+    ```pre
+    -w PATH or -wPATH, --with-compiler=PATH
+                                 # Give the path to a particular compiler.
+    ```
+
+- long option, long description.
+
+    ```pre
+    -f FLAGS or -fFLAGS, --flags=FLAGS
+                                 # Force values for the given flags in Cabal
+                                   conditionals in the .cabal file. E.g.,
+                                   --flags="debug -usebytestrings" forces the
+                                   flag "debug" to true and "usebytestrings" to
+                                   false.
+    ```