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, 68 insertions, 93 deletions

diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst
index 3c606c92bf..5286784809 100644
--- a/docs/users_guide/runtime_control.rst
+++ b/docs/users_guide/runtime_control.rst
@@ -32,7 +32,7 @@ There are four ways to set RTS options:
 -  on the command line between ``+RTS ... -RTS``, when running the
    program (:ref:`rts-opts-cmdline`)
 
--  at compile-time, using :ghc-flag:`-with-rtsopts`
+-  at compile-time, using :ghc-flag:`-with-rtsopts=⟨opts⟩`
    (:ref:`rts-opts-compile-time`)
 
 -  with the environment variable :envvar:`GHCRTS`
@@ -50,9 +50,9 @@ Setting RTS options on the command line
    single: -RTS
    single: --RTS
 
-If you set the :ghc-flag:`-rtsopts` flag appropriately when linking (see
-:ref:`options-linker`), you can give RTS options on the command line
-when running your program.
+If you set the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` flag appropriately when
+linking (see :ref:`options-linker`), you can give RTS options on the command
+line when running your program.
 
 When your Haskell program starts up, the RTS extracts command-line
 arguments bracketed between ``+RTS`` and ``-RTS`` as its own. For example:
@@ -211,29 +211,7 @@ is written through a custom `EventLogWriter`:
 Miscellaneous RTS options
 -------------------------
 
-.. rts-flag:: -V <secs>
-
-    Sets the interval that the RTS clock ticks at. The runtime uses a
-    single timer signal to count ticks; this timer signal is used to
-    control the context switch timer (:ref:`using-concurrent`) and the
-    heap profiling timer :ref:`rts-options-heap-prof`. Also, the time
-    profiler uses the RTS timer signal directly to record time profiling
-    samples.
-
-    Normally, setting the :rts-flag:`-V` option directly is not necessary: the
-    resolution of the RTS timer is adjusted automatically if a short interval is
-    requested with the :rts-flag:`-C` or :rts-flag:`-i` options. However,
-    setting :rts-flag:`-V` is required in order to increase the resolution of
-    the time profiler.
-
-    Using a value of zero disables the RTS clock completely, and has the
-    effect of disabling timers that depend on it: the context switch
-    timer and the heap profiling timer. Context switches will still
-    happen, but deterministically and at a rate much faster than normal.
-    Disabling the interval timer is useful for debugging, because it
-    eliminates a source of non-determinism at runtime.
-
-.. rts-flag:: --install-signal-handlers=<yes|no>
+.. rts-flag:: --install-signal-handlers=⟨yes|no⟩
 
     If yes (the default), the RTS installs signal handlers to catch
     things like ctrl-C. This option is primarily useful for when you are
@@ -246,7 +224,7 @@ Miscellaneous RTS options
     capabilities. To disable the timer signal, use the ``-V0`` RTS
     option (see above).
 
-.. rts-flag:: -xm <address>
+.. rts-flag:: -xm ⟨address⟩
 
     .. index::
        single: -xm; RTS option
@@ -268,14 +246,14 @@ Miscellaneous RTS options
     support for allocating memory in the low 2Gb if available (e.g.
     ``mmap`` with ``MAP_32BIT`` on Linux), or otherwise ``-xm40000000``.
 
-.. rts-flag:: -xq <size>
+.. rts-flag:: -xq ⟨size⟩
 
     :default: 100k
 
     This option relates to allocation limits; for more about this see
     :base-ref:`enableAllocationLimit <GHC-Conc.html#v%3AenableAllocationLimit>`.
     When a thread hits its allocation limit, the RTS throws an exception
-    to the thread, and the thread gets an additional quota of allocation
+    to the thread, and the thread gets an additional quota of allo
     before the exception is raised again, the idea being so that the
     thread can execute its exception handlers. The ``-xq`` controls the
     size of this additional quota.
@@ -303,16 +281,16 @@ performance.
 
     Set the allocation area size used by the garbage
     collector. The allocation area (actually generation 0 step 0) is
-    fixed and is never resized (unless you use :rts-flag:`-H`, below).
+    fixed and is never resized (unless you use :rts-flag:`-H [⟨size⟩]`, below).
 
     Increasing the allocation area size may or may not give better
     performance (a bigger allocation area means worse cache behaviour
     but fewer garbage collections and less promotion).
 
-    With only 1 generation (e.g. ``-G1``, see :rts-flag:`-G`) the ``-A`` option
-    specifies the minimum allocation area, since the actual size of the
-    allocation area will be resized according to the amount of data in the heap
-    (see :rts-flag:`-F`, below).
+    With only 1 generation (e.g. ``-G1``, see :rts-flag:`-G ⟨generations⟩`) the
+    ``-A`` option specifies the minimum allocation area, since the actual size
+    of the allocation area will be resized according to the amount of data in
+    the heap (see :rts-flag:`-F ⟨factor⟩`, below).
 
 .. rts-flag:: -AL ⟨size⟩
 
@@ -349,10 +327,10 @@ performance.
     .. index::
        single: old generation, size
 
-    Set the minimum size of the old generation. The old
-    generation is collected whenever it grows to this size or the value
-    of the :rts-flag:`-F` option multiplied by the size of the live data at the
-    previous major collection, whichever is larger.
+    Set the minimum size of the old generation. The old generation is collected
+    whenever it grows to this size or the value of the :rts-flag:`-F ⟨factor⟩`
+    option multiplied by the size of the live data at the previous major
+    collection, whichever is larger.
 
 .. rts-flag:: -n ⟨size⟩
 
@@ -395,8 +373,8 @@ performance.
     The compaction algorithm is slower than the copying algorithm, but
     the savings in memory use can be considerable.
 
-    For a given heap size (using the :ghc-flag:`-H` option), compaction can in
-    fact reduce the GC cost by allowing fewer GCs to be performed. This
+    For a given heap size (using the :ghc-flag:`-H ⟨size⟩` option), compaction
+    can in fact reduce the GC cost by allowing fewer GCs to be performed. This
     is more likely when the ratio of live data to heap size is high, say
     greater than 30%.
 
@@ -409,11 +387,10 @@ performance.
 
     :default: 30
 
-    Automatically enable compacting collection when the
-    live data exceeds ⟨n⟩% of the maximum heap size (see the :rts-flag:`-M`
-    option). Note that the maximum heap size is unlimited by default, so
-    this option has no effect unless the maximum heap size is set with
-    ``-M ⟨size⟩.``
+    Automatically enable compacting collection when the live data exceeds ⟨n⟩%
+    of the maximum heap size (see the :rts-flag:`-M ⟨size⟩` option). Note that
+    the maximum heap size is unlimited by default, so this option has no effect
+    unless the maximum heap size is set with ``-M ⟨size⟩.``
 
 .. rts-flag:: -F ⟨factor⟩
 
@@ -429,13 +406,13 @@ performance.
     when we last collected it, then by default we'll wait until it grows
     to 4M before collecting it again.
 
-    The default seems to work well here. If you have plenty of memory,
-    it is usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H`) than to
+    The default seems to work well here. If you have plenty of memory, it is
+    usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H [⟨size⟩]`) than to
     increase ``-F ⟨factor⟩.``
 
-    The ``-F`` setting will be automatically reduced by the garbage
+    The ``-F ⟨factor⟩`` setting will be automatically reduced by the garbage
     collector when the maximum heap size (the ``-M ⟨size⟩`` setting, see
-    :rts-flag:`-M`) is approaching.
+    :rts-flag:`-M ⟨size⟩`) is approaching.
 
 .. rts-flag:: -G ⟨generations⟩
 
@@ -452,13 +429,13 @@ performance.
     get collected.
 
     Specifying 1 generation with ``+RTS -G1`` gives you a simple 2-space
-    collector, as you would expect. In a 2-space collector, the :rts-flag:`-A`
-    option specifies the *minimum* allocation area size, since the allocation
-    area will grow with the amount of live data in the heap. In a
-    multi-generational collector the allocation area is a fixed size (unless you
-    use the :rts-flag:`-H` option).
+    collector, as you would expect. In a 2-space collector, the :rts-flag:`-A
+    ⟨size⟩` option specifies the *minimum* allocation area size, since the
+    allocation area will grow with the amount of live data in the heap. In a
+    multi-generational collector the allocation area is a fixed size (unless
+    you use the :rts-flag:`-H [⟨size⟩]` option).
 
-.. rts-flag:: -qg <gen>
+.. rts-flag:: -qg ⟨gen⟩
 
     :default: 0
     :since: 6.12.1
@@ -466,17 +443,16 @@ performance.
     Use parallel GC in generation ⟨gen⟩ and higher. Omitting ⟨gen⟩ turns off the
     parallel GC completely, reverting to sequential GC.
 
-    The default parallel GC settings are usually suitable for parallel
-    programs (i.e. those using ``par``, Strategies, or with multiple
-    threads). However, it is sometimes beneficial to enable the parallel
-    GC for a single-threaded sequential program too, especially if the
-    program has a large amount of heap data and GC is a significant
-    fraction of runtime. To use the parallel GC in a sequential program,
-    enable the parallel runtime with a suitable :rts-flag:`-N` option, and
-    additionally it might be beneficial to restrict parallel GC to the
-    old generation with ``-qg1``.
+    The default parallel GC settings are usually suitable for parallel programs
+    (i.e. those using ``par``, Strategies, or with multiple threads). However,
+    it is sometimes beneficial to enable the parallel GC for a single-threaded
+    sequential program too, especially if the program has a large amount of
+    heap data and GC is a significant fraction of runtime. To use the parallel
+    GC in a sequential program, enable the parallel runtime with a suitable
+    :rts-flag:`-N ⟨x⟩` option, and additionally it might be beneficial to
+    restrict parallel GC to the old generation with ``-qg1``.
 
-.. rts-flag:: -qb <gen>
+.. rts-flag:: -qb ⟨gen⟩
 
     :default: 1 for ``-A`` < 32M, 0 otherwise
     :since: 6.12.1
@@ -494,7 +470,7 @@ performance.
     program it is sometimes beneficial to disable load-balancing
     entirely with ``-qb``.
 
-.. rts-flag:: -qn <x>
+.. rts-flag:: -qn ⟨x⟩
 
     :default: the value of ``-N`` or the number of CPU cores,
               whichever is smaller.
@@ -526,10 +502,10 @@ performance.
     .. index::
        single: heap size, suggested
 
-    This option provides a "suggested heap size" for the
-    garbage collector. Think of ``-Hsize`` as a variable :rts-flag:`-A` option.
-    It says: I want to use at least ⟨size⟩ bytes, so use whatever is
-    left over to increase the ``-A`` value.
+    This option provides a "suggested heap size" for the garbage collector.
+    Think of ``-Hsize`` as a variable :rts-flag:`-A ⟨size⟩` option.  It says: I
+    want to use at least ⟨size⟩ bytes, so use whatever is left over to increase
+    the ``-A`` value.
 
     This option does not put a *limit* on the heap size: the heap may
     grow beyond the given size as usual.
@@ -597,18 +573,17 @@ performance.
     .. index::
        single: stack; chunk size
 
-    Set the size of "stack chunks". When a thread's
-    current stack overflows, a new stack chunk is created and added to
-    the thread's stack, until the limit set by :rts-flag:`-K` is reached.
+    Set the size of "stack chunks". When a thread's current stack overflows, a
+    new stack chunk is created and added to the thread's stack, until the limit
+    set by :rts-flag:`-K ⟨size⟩` is reached.
 
-    The advantage of smaller stack chunks is that the garbage collector
-    can avoid traversing stack chunks if they are known to be unmodified
-    since the last collection, so reducing the chunk size means that the
-    garbage collector can identify more stack as unmodified, and the GC
-    overhead might be reduced. On the other hand, making stack chunks
-    too small adds some overhead as there will be more
-    overflow/underflow between chunks. The default setting of 32k
-    appears to be a reasonable compromise in most cases.
+    The advantage of smaller stack chunks is that the garbage collector can
+    avoid traversing stack chunks if they are known to be unmodified since the
+    last collection, so reducing the chunk size means that the garbage
+    collector can identify more stack as unmodified, and the GC overhead might
+    be reduced. On the other hand, making stack chunks too small adds some
+    overhead as there will be more overflow/underflow between chunks. The
+    default setting of 32k appears to be a reasonable compromise in most cases.
 
 .. rts-flag:: -kb ⟨size⟩
 
@@ -623,10 +598,10 @@ performance.
     immediate underflow and repeated overflow/underflow at the boundary.
     The amount of stack moved is set by the ``-kb`` option.
 
-    Note that to avoid wasting space, this value should typically be
-    less than 10% of the size of a stack chunk (:rts-flag:`-kc`), because in a
-    chain of stack chunks, each chunk will have a gap of unused space of
-    this size.
+    Note that to avoid wasting space, this value should typically be less than
+    10% of the size of a stack chunk (:rts-flag:`-kc ⟨size⟩`), because in a
+    chain of stack chunks, each chunk will have a gap of unused space of this
+    size.
 
 .. rts-flag:: -K ⟨size⟩
 
@@ -680,7 +655,7 @@ performance.
     .. index::
        single: heap size, grace
 
-    If the program's heap exceeds the value set by :rts-flag:`-M`, the
+    If the program's heap exceeds the value set by :rts-flag:`-M ⟨size⟩`, the
     RTS throws an exception to the program, and the program gets an
     additional quota of allocation before the exception is raised
     again, the idea being so that the program can execute its
@@ -743,9 +718,9 @@ RTS options to produce runtime statistics
 -----------------------------------------
 
 .. rts-flag:: -T
-              -t [<file>]
-              -s [<file>]
-              -S [<file>]
+              -t [⟨file⟩]
+              -s [⟨file⟩]
+              -S [⟨file⟩]
               --machine-readable
 
     These options produce runtime-system statistics, such as the amount
@@ -950,7 +925,7 @@ executables:
     ``THUNK``). To get a more detailed profile, use the full profiling support
     (:ref:`profiling`). Can be shortened to ``-h``.
 
-.. rts-flag:: -L <n>
+.. rts-flag:: -L ⟨n⟩
 
     :default: 25 characters
 
@@ -980,7 +955,7 @@ When the program is linked with the :ghc-flag:`-eventlog` option
 
 -  As text to standard output, for debugging purposes.
 
-.. rts-flag:: -l <flags>
+.. rts-flag:: -l ⟨flags⟩
 
     Log events in binary format. Without any ⟨flags⟩ specified, this
     logs a default set of events, suitable for use with tools like ThreadScope.
@@ -1091,7 +1066,7 @@ recommended for everyday use!
 
     Produce "ticky-ticky" statistics at the end of the program run (only
     available if the program was linked with :ghc-flag:`-debug`). The ⟨file⟩
-    business works just like on the :rts-flag:`-S` RTS option, above.
+    business works just like on the :rts-flag:`-S [⟨file⟩]` RTS option, above.
 
     For more information on ticky-ticky profiling, see
     :ref:`ticky-ticky`.