users-guide: Standardize and repair all flag references

This patch does three things:

1.) It simplifies the flag parsing code in `conf.py` to properly display
flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
references must include the associated arguments. Documentation has been
added to `editing-guide.rst` to explain this.

2.) It normalizes all flag definitions to a similar format. Notably, all
instances of `<>` have been replaced with `⟨⟩`. All references across the
users guide have been updated to match.

3.) It fixes a couple issues with the flag reference table's generation code,
which did not handle comma separated flags in the same cell and did not
properly reference flags with arguments.

Test Plan:
`SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
references. All remaining errors are references to flags without any
documentation.

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #13980

Differential Revision: https://phabricator.haskell.org/D3778

16 files changed, 79 insertions, 68 deletions

diff --git a/utils/mkUserGuidePart/Main.hs b/utils/mkUserGuidePart/Main.hs
index d517048d36..99f921c8f4 100644
--- a/utils/mkUserGuidePart/Main.hs
+++ b/utils/mkUserGuidePart/Main.hs
@@ -48,7 +48,7 @@ whatGlasgowExtsDoes = unlines
 -- the user's guide.
 flagsTable :: [Flag] -> ReST
 flagsTable theFlags =
-    table [50, 100, 30, 55]
+    table [60, 100, 30, 55]
           ["Flag", "Description", "Type", "Reverse"]
           (map flagRow theFlags)
   where
@@ -72,7 +72,12 @@ inlineCode s = "``" ++ s ++ "``"
 -- @:hi:`Hello world`@.
 role :: String -> String -> ReST
 role _ "" = ""
-role r c  = concat [":",r,":`",c,"`"]
+role r c  = concat [":",r,":`",flag,"`",next]
+  where
+    -- Handle multiple comma separated flags
+    (flag, rest) =  span (/= ',') c
+    next | rest == "" = rest
+         | otherwise  = concat [", ", role r $ dropWhile (/= '-') rest]
 
 heading :: Char -> String -> ReST
 heading chr title = unlines
diff --git a/utils/mkUserGuidePart/Options/CompilerDebugging.hs b/utils/mkUserGuidePart/Options/CompilerDebugging.hs
index e68216bdeb..1d643a1385 100644
--- a/utils/mkUserGuidePart/Options/CompilerDebugging.hs
+++ b/utils/mkUserGuidePart/Options/CompilerDebugging.hs
@@ -136,7 +136,7 @@ compilerDebuggingOptions =
          , flagDescription = "Dump typechecker output"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-dth-dec-file"
+  , flag { flagName = "-dth-dec-file=⟨file⟩"
          , flagDescription =
            "Show evaluated TH declarations in a .th.hs file"
          , flagType = DynamicFlag
@@ -186,7 +186,7 @@ compilerDebuggingOptions =
            "Set the depth for printing expressions in error msgs"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-dppr-cols⟨N⟩"
+  , flag { flagName = "-dppr-cols=⟨n⟩"
          , flagDescription =
            "Set the width of debugging output. For example ``-dppr-cols200``"
          , flagType = DynamicFlag
diff --git a/utils/mkUserGuidePart/Options/FindingImports.hs b/utils/mkUserGuidePart/Options/FindingImports.hs
index b976cdbef8..65f5ebacba 100644
--- a/utils/mkUserGuidePart/Options/FindingImports.hs
+++ b/utils/mkUserGuidePart/Options/FindingImports.hs
@@ -4,7 +4,7 @@ import Types
 
 findingImportsOptions :: [Flag]
 findingImportsOptions =
-  [ flag { flagName = "-i⟨dir1⟩:⟨dir2⟩:..."
+  [ flag { flagName = "-i⟨dir⟩[:⟨dir⟩]*"
          , flagDescription = "add ⟨dir⟩, ⟨dir2⟩, etc. to import path"
          , flagType = DynamicSettableFlag
          }
diff --git a/utils/mkUserGuidePart/Options/Interactive.hs b/utils/mkUserGuidePart/Options/Interactive.hs
index 142e207e67..6bc413909d 100644
--- a/utils/mkUserGuidePart/Options/Interactive.hs
+++ b/utils/mkUserGuidePart/Options/Interactive.hs
@@ -56,7 +56,7 @@ interactiveOptions =
            "<ghci-import-qualified>`"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-interactive-print"
+  , flag { flagName = "-interactive-print ⟨expr⟩"
          , flagDescription =
            ":ref:`Select the function to use for printing evaluated " ++
            "expressions in GHCi <ghci-interactive-print>`"
diff --git a/utils/mkUserGuidePart/Options/Linking.hs b/utils/mkUserGuidePart/Options/Linking.hs
index 3142020692..20d6f1feb2 100644
--- a/utils/mkUserGuidePart/Options/Linking.hs
+++ b/utils/mkUserGuidePart/Options/Linking.hs
@@ -27,29 +27,29 @@ linkingOptions =
            "Selects one of a number of modes for finding shared libraries at runtime."
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-framework⟨name⟩"
+  , flag { flagName = "-framework ⟨name⟩"
          , flagDescription =
            "On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This " ++
            "option corresponds to the ``-framework`` option for Apple's Linker."
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-framework-path⟨name⟩"
+  , flag { flagName = "-framework-path ⟨dir⟩"
          , flagDescription =
            "On Darwin/OS X/iOS only, add ⟨dir⟩ to the list of directories " ++
            "searched for frameworks. This option corresponds to the ``-F`` "++
            "option for Apple's Linker."
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-l⟨lib⟩"
+  , flag { flagName = "-l ⟨lib⟩"
          , flagDescription = "Link in library ⟨lib⟩"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-L⟨dir⟩"
+  , flag { flagName = "-L ⟨dir⟩"
          , flagDescription =
            "Add ⟨dir⟩ to the list of directories searched for libraries"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-main-is"
+  , flag { flagName = "-main-is ⟨thing⟩"
          , flagDescription = "Set main module and function"
          , flagType = DynamicFlag
          }
@@ -61,7 +61,7 @@ linkingOptions =
          , flagDescription = "Don't assume this program contains ``main``"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-rtsopts,-rtsopts={none,some,all}"
+  , flag { flagName = "-rtsopts[=⟨none|some|all⟩]"
          , flagDescription =
            "Control whether the RTS behaviour can be tweaked via command-line"++
            "flags and the ``GHCRTS`` environment variable. Using ``none`` " ++
@@ -70,13 +70,14 @@ linkingOptions =
            "argument at all) means that all RTS flags are permitted."
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-with-rtsopts=opts"
+  , flag { flagName = "-with-rtsopts=⟨opts⟩"
          , flagDescription = "Set the default RTS options to ⟨opts⟩."
          , flagType = DynamicFlag
          }
   , flag { flagName = "-no-rtsopts-suggestions"
          , flagDescription =
-           "Don't print RTS suggestions about linking with :ghc-flag:`-rtsopts`."
+           "Don't print RTS suggestions about linking with "++
+           ":ghc-flag:`-rtsopts[=⟨none|some|all⟩]`."
          , flagType = DynamicFlag
          }
   , flag { flagName = "-no-link"
diff --git a/utils/mkUserGuidePart/Options/Misc.hs b/utils/mkUserGuidePart/Options/Misc.hs
index c542fa39d6..f1d4336806 100644
--- a/utils/mkUserGuidePart/Options/Misc.hs
+++ b/utils/mkUserGuidePart/Options/Misc.hs
@@ -4,9 +4,10 @@ import Types
 
 miscOptions :: [Flag]
 miscOptions =
-  [ flag { flagName = "-jN"
+  [ flag { flagName = "-j[⟨n⟩]"
          , flagDescription =
-           "When compiling with :ghc-flag:`--make`, compile ⟨N⟩ modules in parallel."
+           "When compiling with :ghc-flag:`--make`, compile ⟨n⟩ modules" ++
+           " in parallel."
          , flagType = DynamicFlag
          }
   , flag { flagName = "-fno-hi-version-check"
diff --git a/utils/mkUserGuidePart/Options/Modes.hs b/utils/mkUserGuidePart/Options/Modes.hs
index 792ee9f02e..e0afb61999 100644
--- a/utils/mkUserGuidePart/Options/Modes.hs
+++ b/utils/mkUserGuidePart/Options/Modes.hs
@@ -21,12 +21,12 @@ modeOptions =
            "``make``; see :ref:`make-mode` for details."
          , flagType = ModeFlag
          }
-  , flag { flagName = "-e expr"
+  , flag { flagName = "-e ⟨expr⟩"
          , flagDescription =
            "Evaluate ``expr``; see :ref:`eval-mode` for details."
          , flagType = ModeFlag
          }
-  , flag { flagName = "--show-iface"
+  , flag { flagName = "--show-iface ⟨file⟩"
          , flagDescription = "display the contents of an interface file."
          , flagType = ModeFlag
          }
diff --git a/utils/mkUserGuidePart/Options/Packages.hs b/utils/mkUserGuidePart/Options/Packages.hs
index 373773cf04..d2aed64c63 100644
--- a/utils/mkUserGuidePart/Options/Packages.hs
+++ b/utils/mkUserGuidePart/Options/Packages.hs
@@ -4,24 +4,26 @@ import Types
 
 packagesOptions :: [Flag]
 packagesOptions =
-  [ flag { flagName = "-this-unit-id ⟨P⟩"
-         , flagDescription = "Compile to be part of unit (i.e. package) ⟨P⟩"
+  [ flag { flagName = "-this-unit-id ⟨unit-id⟩"
+         , flagDescription =
+           "Compile to be part of unit (i.e. package)" ++
+           " ⟨unit-id⟩"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-package ⟨P⟩"
-         , flagDescription = "Expose package ⟨P⟩"
+  , flag { flagName = "-package ⟨pkg⟩"
+         , flagDescription = "Expose package ⟨pkg⟩"
          , flagType = DynamicSettableFlag
          }
   , flag { flagName = "-hide-all-packages"
          , flagDescription = "Hide all packages by default"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-hide-package ⟨name⟩"
-         , flagDescription = "Hide package ⟨P⟩"
+  , flag { flagName = "-hide-package ⟨pkg⟩"
+         , flagDescription = "Hide package ⟨pkg⟩"
          , flagType = DynamicSettableFlag
          }
-  , flag { flagName = "-ignore-package ⟨name⟩"
-         , flagDescription = "Ignore package ⟨P⟩"
+  , flag { flagName = "-ignore-package ⟨pkg⟩"
+         , flagDescription = "Ignore package ⟨pkg⟩"
          , flagType = DynamicSettableFlag
          }
   , flag { flagName = "-package-db ⟨file⟩"
@@ -49,15 +51,17 @@ packagesOptions =
          , flagType = DynamicFlag
          }
   , flag { flagName = "-no-auto-link-packages"
-         , flagDescription = "Don't automatically link in the base and rts packages."
+         , flagDescription =
+           "Don't automatically link in the base and rts packages."
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-trust ⟨P⟩"
-         , flagDescription = "Expose package ⟨P⟩ and set it to be trusted"
+  , flag { flagName = "-trust ⟨pkg⟩"
+         , flagDescription = "Expose package ⟨pkg⟩ and set it to be trusted"
          , flagType = DynamicSettableFlag
          }
-  , flag { flagName = "-distrust ⟨P⟩"
-         , flagDescription = "Expose package ⟨P⟩ and set it to be distrusted"
+  , flag { flagName = "-distrust ⟨pkg⟩"
+         , flagDescription =
+           "Expose package ⟨pkg⟩ and set it to be distrusted"
          , flagType = DynamicSettableFlag
          }
   , flag { flagName = "-distrust-all"
diff --git a/utils/mkUserGuidePart/Options/PhasePrograms.hs b/utils/mkUserGuidePart/Options/PhasePrograms.hs
index 65ead95178..9e13fb8b26 100644
--- a/utils/mkUserGuidePart/Options/PhasePrograms.hs
+++ b/utils/mkUserGuidePart/Options/PhasePrograms.hs
@@ -4,53 +4,53 @@ import Types
 
 phaseProgramsOptions :: [Flag]
 phaseProgramsOptions =
-  [ flag { flagName = "-pgmL⟨cmd⟩"
+  [ flag { flagName = "-pgmL ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the literate pre-processor"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmP⟨cmd⟩"
+  , flag { flagName = "-pgmP ⟨cmd⟩"
          , flagDescription =
            "Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmc⟨cmd⟩"
+  , flag { flagName = "-pgmc ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the C compiler"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmlo⟨cmd⟩"
+  , flag { flagName = "-pgmlo ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the LLVM optimiser"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmlc⟨cmd⟩"
+  , flag { flagName = "-pgmlc ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the LLVM compiler"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgms⟨cmd⟩"
+  , flag { flagName = "-pgms ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the splitter"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgma⟨cmd⟩"
+  , flag { flagName = "-pgma ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the assembler"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgml⟨cmd⟩"
+  , flag { flagName = "-pgml ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the linker"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmdll⟨cmd⟩"
+  , flag { flagName = "-pgmdll ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the DLL generator"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmF⟨cmd⟩"
+  , flag { flagName = "-pgmF ⟨cmd⟩"
          , flagDescription = "Use ⟨cmd⟩ as the pre-processor (with ``-F`` only)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmwindres⟨cmd⟩"
+  , flag { flagName = "-pgmwindres ⟨cmd⟩"
          , flagDescription =
            "Use ⟨cmd⟩ as the program for embedding manifests on Windows."
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-pgmlibtool⟨cmd⟩"
+  , flag { flagName = "-pgmlibtool ⟨cmd⟩"
          , flagDescription =
            "Use ⟨cmd⟩ as the command for libtool (with ``-staticlib`` only)."
          , flagType = DynamicFlag
diff --git a/utils/mkUserGuidePart/Options/PhaseSpecific.hs b/utils/mkUserGuidePart/Options/PhaseSpecific.hs
index cbd79f18a4..bf903bc8f3 100644
--- a/utils/mkUserGuidePart/Options/PhaseSpecific.hs
+++ b/utils/mkUserGuidePart/Options/PhaseSpecific.hs
@@ -4,43 +4,43 @@ import Types
 
 phaseSpecificOptions :: [Flag]
 phaseSpecificOptions =
-  [ flag { flagName = "-optL⟨option⟩"
+  [ flag { flagName = "-optL ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the literate pre-processor"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optP⟨option⟩"
+  , flag { flagName = "-optP ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to cpp (with ``-cpp`` only)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optF⟨option⟩"
+  , flag { flagName = "-optF ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the custom pre-processor"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optc⟨option⟩"
+  , flag { flagName = "-optc ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the C compiler"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optlo⟨option⟩"
+  , flag { flagName = "-optlo ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the LLVM optimiser"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optlc⟨option⟩"
+  , flag { flagName = "-optlc ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the LLVM compiler"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-opta⟨option⟩"
+  , flag { flagName = "-opta ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the assembler"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optl⟨option⟩"
+  , flag { flagName = "-optl ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the linker"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optdll⟨option⟩"
+  , flag { flagName = "-optdll ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to the DLL generator"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-optwindres⟨option⟩"
+  , flag { flagName = "-optwindres ⟨option⟩"
          , flagDescription = "pass ⟨option⟩ to ``windres``."
          , flagType = DynamicFlag
          }
diff --git a/utils/mkUserGuidePart/Options/Phases.hs b/utils/mkUserGuidePart/Options/Phases.hs
index f302f569dd..54c886e310 100644
--- a/utils/mkUserGuidePart/Options/Phases.hs
+++ b/utils/mkUserGuidePart/Options/Phases.hs
@@ -7,7 +7,7 @@ phaseOptions =
   [ flag { flagName = "-F"
          , flagDescription =
            "Enable the use of a :ref:`pre-processor <pre-processor>` "++
-           "(set with :ghc-flag:`-pgmF`)"
+           "(set with :ghc-flag:`-pgmF ⟨cmd⟩`)"
          , flagType = DynamicFlag
          }
   , flag { flagName = "-E"
@@ -26,7 +26,7 @@ phaseOptions =
          , flagDescription = "Stop after generating object (``.o``) file"
          , flagType = ModeFlag
          }
-  , flag { flagName = "-x⟨suffix⟩"
+  , flag { flagName = "-x ⟨suffix⟩"
          , flagDescription = "Override default behaviour for source files"
          , flagType = DynamicFlag
          }
diff --git a/utils/mkUserGuidePart/Options/Plugin.hs b/utils/mkUserGuidePart/Options/Plugin.hs
index 1ae7d6e536..a948b94c9f 100644
--- a/utils/mkUserGuidePart/Options/Plugin.hs
+++ b/utils/mkUserGuidePart/Options/Plugin.hs
@@ -8,7 +8,7 @@ pluginOptions =
          , flagDescription = "Load a plugin exported by a given module"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-fplugin-opt=⟨module:args⟩"
+  , flag { flagName = "-fplugin-opt=⟨module⟩:⟨args⟩"
          , flagDescription =
            "Give arguments to a plugin module; module must be specified with "++
            "``-fplugin``"
diff --git a/utils/mkUserGuidePart/Options/ProgramCoverage.hs b/utils/mkUserGuidePart/Options/ProgramCoverage.hs
index c7b2894668..8da7df37b7 100644
--- a/utils/mkUserGuidePart/Options/ProgramCoverage.hs
+++ b/utils/mkUserGuidePart/Options/ProgramCoverage.hs
@@ -9,7 +9,7 @@ programCoverageOptions =
            "Turn on Haskell program coverage instrumentation"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-hpcdir dir"
+  , flag { flagName = "-hpcdir ⟨dir⟩"
          , flagDescription =
            "Directory to deposit ``.mix`` files during compilation "++
            "(default is ``.hpc``)"
diff --git a/utils/mkUserGuidePart/Options/RedirectingOutput.hs b/utils/mkUserGuidePart/Options/RedirectingOutput.hs
index 62fe99a650..162131166c 100644
--- a/utils/mkUserGuidePart/Options/RedirectingOutput.hs
+++ b/utils/mkUserGuidePart/Options/RedirectingOutput.hs
@@ -16,7 +16,7 @@ redirectingOutputOptions =
          , flagDescription = "set the suffix to use for interface files"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-o ⟨filename⟩"
+  , flag { flagName = "-o ⟨file⟩"
          , flagDescription = "set output filename"
          , flagType = DynamicFlag
          }
@@ -24,7 +24,7 @@ redirectingOutputOptions =
          , flagDescription = "set directory for object files"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-ohi ⟨filename⟩"
+  , flag { flagName = "-ohi ⟨file⟩"
          , flagDescription = "set the filename in which to put the interface"
          , flagType = DynamicFlag
          }
@@ -44,15 +44,15 @@ redirectingOutputOptions =
          , flagDescription = "set output directory"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-dyno <filename>"
+  , flag { flagName = "-dyno ⟨file⟩"
          , flagDescription = "Set the output filename for dynamic object files (see ``-dynamic-too``)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-dynosuf <suffix>"
+  , flag { flagName = "-dynosuf ⟨suffix⟩"
          , flagDescription = "Set the object suffix for dynamic object files (see ``-dynamic-too``)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-dynhisuf <suffix>"
+  , flag { flagName = "-dynhisuf ⟨suffix⟩"
          , flagDescription = "Set the hi suffix for dynamic object files (see ``-dynamic-too``)"
          , flagType = DynamicFlag
          }
diff --git a/utils/mkUserGuidePart/Options/Verbosity.hs b/utils/mkUserGuidePart/Options/Verbosity.hs
index ff1e5a9a90..ba58e6210a 100644
--- a/utils/mkUserGuidePart/Options/Verbosity.hs
+++ b/utils/mkUserGuidePart/Options/Verbosity.hs
@@ -34,7 +34,7 @@ verbosityOptions =
   , flag { flagName = "-fprint-explicit-kinds"
          , flagDescription =
            "Print explicit kind foralls and kind arguments in types. " ++
-           "See also :ghc-flag:`-XKindSignature`"
+           "See also :ghc-flag:`-XKindSignatures`"
          , flagType = DynamicFlag
          , flagReverse = "-fno-print-explicit-kinds"
          }
diff --git a/utils/mkUserGuidePart/Options/Warnings.hs b/utils/mkUserGuidePart/Options/Warnings.hs
index 620c7312e7..da88ec68b6 100644
--- a/utils/mkUserGuidePart/Options/Warnings.hs
+++ b/utils/mkUserGuidePart/Options/Warnings.hs
@@ -31,20 +31,20 @@ warningsOptions =
          , flagType = DynamicFlag
          , flagReverse = "-Wwarn"
          }
-  , flag { flagName = "-Werror=<wflag>"
+  , flag { flagName = "-Werror=⟨wflag⟩"
          , flagDescription = "make a specific warning fatal"
          , flagType = DynamicFlag
-         , flagReverse = "-Wwarn=<wflag>"
+         , flagReverse = "-Wwarn=⟨wflag⟩"
          }
   , flag { flagName = "-Wwarn"
          , flagDescription = "make warnings non-fatal"
          , flagType = DynamicFlag
          , flagReverse = "-Werror"
          }
-  , flag { flagName = "-Wwarn=<wflag>"
+  , flag { flagName = "-Wwarn=⟨wflag⟩"
          , flagDescription = "make a specific warning non-fatal"
          , flagType = DynamicFlag
-         , flagReverse = "-Werror=<wflag>"
+         , flagReverse = "-Werror=⟨wflag⟩"
          }
   , flag { flagName = "-Wunrecognised-warning-flags"
          , flagDescription =
@@ -150,7 +150,7 @@ warningsOptions =
          , flagType = DynamicFlag
          , flagReverse = "-Wno-incomplete-uni-patterns"
          }
-  , flag { flagName = "-Wmax-pmcheck-iterations=<N>"
+  , flag { flagName = "-fmax-pmcheck-iterations=⟨n⟩"
          , flagDescription =
            "the iteration limit for the pattern match checker"
          , flagType = DynamicFlag