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

1 files changed, 21 insertions, 5 deletions

diff --git a/docs/users_guide/editing-guide.rst b/docs/users_guide/editing-guide.rst
index b8ba081972..cf2ebdd9d3 100644
--- a/docs/users_guide/editing-guide.rst
+++ b/docs/users_guide/editing-guide.rst
@@ -317,7 +317,7 @@ respectively. For instance,
 
 .. code-block:: rest
 
-    .. rts-flag:: -C <seconds>
+    .. rts-flag:: -C ⟨seconds⟩
 
        :default: 20 milliseconds
 
@@ -325,13 +325,28 @@ respectively. For instance,
 
 Will be rendered as,
 
-    .. rts-flag:: -C <seconds>
+    .. rts-flag:: -C ⟨seconds⟩
+       :noindex:
 
        :default: 20 milliseconds
 
        Sets the context switch interval to ⟨s⟩ seconds.
 
-and will have an associated index entry generated automatically.
+and will have an associated index entry generated automatically. Note that, as
+in Style Conventions below, we use ``⟨⟩`` instead of less-than/greater-than
+signs. To reference a ``ghc-flag`` or ``rts-flag``, you must match the
+definition exactly, including the arguments. A quick way to find the exact
+names and special characters is,
+
+.. code-block:: sh
+    
+    $ git grep -- "flag:: -o "
+
+which will generate the appropriate,
+
+.. code-block:: none
+
+    separate_compilation.rst:.. ghc-flag:: -o ⟨file⟩
 
 GHCi commands
 ~~~~~~~~~~~~~
@@ -341,13 +356,14 @@ instance, we can describe the GHCi ``:module`` command,
 
 .. code-block:: rest
 
-    .. ghci-cmd:: :module [*] <file>
+    .. ghci-cmd:: :module; [*]⟨file⟩
 
         Load a module
 
 which will be rendered as,
 
-    .. ghci-cmd:: :module [*] <file>
+    .. ghci-cmd:: :module; [*]⟨file⟩
+        :noindex:
 
         Load a module