users-guide: Standardize and repair all flag references
authorPatrick Dougherty <patrick.doc@ameritech.net>
Sun, 23 Jul 2017 16:55:37 +0000 (12:55 -0400)
committerBen Gamari <ben@smart-cactus.org>
Sun, 23 Jul 2017 19:47:21 +0000 (15:47 -0400)
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

36 files changed:
docs/users_guide/8.2.1-notes.rst
docs/users_guide/conf.py
docs/users_guide/debug-info.rst
docs/users_guide/debugging.rst
docs/users_guide/editing-guide.rst
docs/users_guide/extending_ghc.rst
docs/users_guide/ffi-chap.rst
docs/users_guide/ghci.rst
docs/users_guide/glasgow_exts.rst
docs/users_guide/packages.rst
docs/users_guide/phases.rst
docs/users_guide/profiling.rst
docs/users_guide/runtime_control.rst
docs/users_guide/separate_compilation.rst
docs/users_guide/shared_libs.rst
docs/users_guide/sooner.rst
docs/users_guide/using-concurrent.rst
docs/users_guide/using-optimisation.rst
docs/users_guide/using-warnings.rst
docs/users_guide/using.rst
utils/mkUserGuidePart/Main.hs
utils/mkUserGuidePart/Options/CompilerDebugging.hs
utils/mkUserGuidePart/Options/FindingImports.hs
utils/mkUserGuidePart/Options/Interactive.hs
utils/mkUserGuidePart/Options/Linking.hs
utils/mkUserGuidePart/Options/Misc.hs
utils/mkUserGuidePart/Options/Modes.hs
utils/mkUserGuidePart/Options/Packages.hs
utils/mkUserGuidePart/Options/PhasePrograms.hs
utils/mkUserGuidePart/Options/PhaseSpecific.hs
utils/mkUserGuidePart/Options/Phases.hs
utils/mkUserGuidePart/Options/Plugin.hs
utils/mkUserGuidePart/Options/ProgramCoverage.hs
utils/mkUserGuidePart/Options/RedirectingOutput.hs
utils/mkUserGuidePart/Options/Verbosity.hs
utils/mkUserGuidePart/Options/Warnings.hs

index e2231ba..d3ec447 100644 (file)
@@ -328,9 +328,9 @@ Runtime system
   This is supported on Linux and Windows systems.
 
 - The garbage collector can be told to use fewer threads than the
-  global number of capabilities set by :rts-flag:`-N`. By default, the garbage
+  global number of capabilities set by :rts-flag:`-N ⟨x⟩`. By default, the garbage
   collector will use a number of threads equal to the lesser of the global number
-  of capabilities or the number of physical cores. See :rts-flag:`-qn`, and a
+  of capabilities or the number of physical cores. See :rts-flag:`-qn ⟨x⟩`, and a
   `blog post <http://simonmar.github.io/posts/2016-12-08-Haskell-in-the-datacentre.html>`_
   that describes this.
 
index 8a4c18f..12ecee9 100644 (file)
@@ -116,35 +116,39 @@ texinfo_documents = [
 from sphinx import addnodes
 from docutils import nodes
 
+# The following functions parse flag declarations, and then have two jobs. First
+# they modify the docutils node `signode` for the proper display of the
+# declaration. Second, they return the name used to reference the flag.
+# (i.e. return "name" implies you reference the flag with :flag:`name`)
 def parse_ghci_cmd(env, sig, signode):
-    name = sig.split(';')[0]
-    sig = sig.replace(';', '')
-    signode += addnodes.desc_name(name, sig)
+    parts = sig.split(';')
+    name = parts[0]
+    args = ''
+    if len(parts) > 1:
+        args = parts[1]
+    # Bold name
+    signode += addnodes.desc_name(name, name)
+    # Smaller args
+    signode += addnodes.desc_addname(args, args)
+    # Reference name
     return name
 
 def parse_flag(env, sig, signode):
+
+    # Break flag into name and args
     import re
-    names = []
-    for i, flag in enumerate(sig.split(',')):
-        flag = flag.strip()
-        sep = '='
-        parts = flag.split('=')
-        if len(parts) == 1:
-            sep=' '
-            parts = flag.split()
-        if len(parts) == 0: continue
-
-        name = parts[0]
-        names.append(name)
-        sig = sep + ' '.join(parts[1:])
-        sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
-        if i > 0:
-            signode += addnodes.desc_name(', ', ', ')
-        signode += addnodes.desc_name(name, name)
-        if len(sig) > 0:
-            signode += addnodes.desc_addname(sig, sig)
-
-    return names[0]
+    parts = re.split('( |=|\\[)', sig, 1)
+    flag = parts[0]
+    args = ''
+    if len(parts) > 1:
+        args = ''.join(parts[1:])
+
+    # Bold printed name
+    signode += addnodes.desc_name(flag, flag)
+    # Smaller arguments
+    signode += addnodes.desc_addname(args, args)
+    # Reference name left unchanged
+    return sig
 
 def setup(app):
     from sphinx.util.docfields import Field, TypedField
index a0aade5..b405600 100644 (file)
@@ -5,7 +5,8 @@ Since the 7.10 release GHC can emit a debugging information to help debugging
 tools understand the code that GHC produces. This debugging information is
 useable by most UNIX debugging tools.
 
-.. ghc-flag:: -g, -g<n>
+.. ghc-flag:: -g
+              -g⟨n⟩
 
     :since: 7.10, numeric levels since 8.0
 
index af937ae..bc15588 100644 (file)
@@ -63,7 +63,7 @@ Dumping out compiler intermediate structures
         Dump Template Haskell expressions that we splice in, and what
         Haskell code the expression evaluates to.
 
-    .. ghc-flag:: -dth-dec-file=<file>
+    .. ghc-flag:: -dth-dec-file=⟨file⟩
 
         Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
 
@@ -282,7 +282,7 @@ Formatting dumps
     with subexpressions beyond the depth replaced by ellipses. This flag
     sets the depth. Its default value is 5.
 
-.. ghc-flag:: -dppr-cols=N
+.. ghc-flag:: -dppr-cols=⟨n⟩
 
     Set the width of debugging output. Use this if your code is wrapping
     too much. For example: ``-dppr-cols=200``.
@@ -412,8 +412,8 @@ Checking for determinism
 
     Set the increment for the generated ``Unique``'s to ⟨i⟩.
 
-    This is useful in combination with :ghc-flag:`-dinitial-unique` to test if the
-    generated files depend on the order of ``Unique``'s.
+    This is useful in combination with :ghc-flag:`-dinitial-unique=⟨s⟩` to test
+    if the generated files depend on the order of ``Unique``'s.
 
     Some interesting values:
 
index b8ba081..cf2ebdd 100644 (file)
@@ -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
 
index a7fb538..4a3e02e 100644 (file)
@@ -190,17 +190,17 @@ restrictions are too onerous,
 Using compiler plugins
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Plugins can be specified on the command line with the :ghc-flag:`-fplugin`
-option. ``-fplugin=module`` where ⟨module⟩ is a module in a registered package
-that exports a plugin. Arguments can be given to plugins with the
-:ghc-flag:`-fplugin-opt` option.
+Plugins can be specified on the command line with the
+:ghc-flag:`-fplugin=⟨module⟩` option where ⟨module⟩ is a
+module in a registered package that exports a plugin. Arguments can be given to
+plugins with the :ghc-flag:`-fplugin-opt=⟨module⟩:⟨args⟩` option.
 
-.. ghc-flag:: -fplugin=<module>
+.. ghc-flag:: -fplugin=⟨module⟩
 
-    Load the plugin in the given module. The module must be a member of a package
-    registered in GHC's package database.
+    Load the plugin in the given module. The module must be a member of a
+    package registered in GHC's package database.
 
-.. ghc-flag:: -fplugin-opt=<module>:<args>
+.. ghc-flag:: -fplugin-opt=⟨module⟩:⟨args⟩
 
     Pass arguments ⟨args⟩ to the given plugin.
 
@@ -228,40 +228,39 @@ control specifically plugin packages:
 
 .. ghc-flag:: -plugin-package ⟨pkg⟩
 
-    This option causes the installed package ⟨pkg⟩ to be exposed
-    for plugins, such as :ghc-flag:`-fplugin`. The
-    package ⟨pkg⟩ can be specified in full with its version number (e.g.
-    ``network-1.0``) or the version number can be omitted if there is
-    only one version of the package installed. If there are multiple
-    versions of ⟨pkg⟩ installed and :ghc-flag:`-hide-all-plugin-packages` was not
-    specified, then all other versions will become hidden.  :ghc-flag:`-plugin-package`
-    supports thinning and renaming described in
-    :ref:`package-thinning-and-renaming`.
+    This option causes the installed package ⟨pkg⟩ to be exposed for plugins,
+    such as :ghc-flag:`-fplugin=⟨module⟩`. The package ⟨pkg⟩ can be specified
+    in full with its version number (e.g.  ``network-1.0``) or the version
+    number can be omitted if there is only one version of the package
+    installed. If there are multiple versions of ⟨pkg⟩ installed and
+    :ghc-flag:`-hide-all-plugin-packages` was not specified, then all other
+    versions will become hidden.  :ghc-flag:`-plugin-package ⟨pkg⟩` supports
+    thinning and renaming described in :ref:`package-thinning-and-renaming`.
 
-    Unlike :ghc-flag:`-package`, this option does NOT cause package ⟨pkg⟩ to be linked
-    into the resulting executable or shared object.
+    Unlike :ghc-flag:`-package ⟨pkg⟩`, this option does NOT cause package ⟨pkg⟩
+    to be linked into the resulting executable or shared object.
 
 .. ghc-flag:: -plugin-package-id ⟨pkg-id⟩
 
-    Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package`, but the
-    package is named by its installed package ID rather than by name. This is a
-    more robust way to name packages, and can be used to select packages that
-    would otherwise be shadowed. Cabal passes :ghc-flag:`-plugin-package-id` flags to
-    GHC.  :ghc-flag:`-plugin-package-id` supports thinning and renaming described in
-    :ref:`package-thinning-and-renaming`.
+    Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package
+    ⟨pkg⟩`, but the package is named by its installed package ID rather than by
+    name.  This is a more robust way to name packages, and can be used to
+    select packages that would otherwise be shadowed. Cabal passes
+    :ghc-flag:`-plugin-package-id ⟨pkg-id⟩` flags to GHC.
+    :ghc-flag:`-plugin-package-id ⟨pkg-id⟩` supports thinning and renaming
+    described in :ref:`package-thinning-and-renaming`.
 
 .. ghc-flag:: -hide-all-plugin-packages
 
-    By default, all exposed packages in the normal, source import
-    namespace are also available for plugins.  This causes those
-    packages to be hidden by default.
-    If you use this flag, then any packages with plugins you require
-    need to be explicitly exposed using
-    :ghc-flag:`-plugin-package` options.
+    By default, all exposed packages in the normal, source import namespace are
+    also available for plugins.  This causes those packages to be hidden by
+    default.  If you use this flag, then any packages with plugins you require
+    need to be explicitly exposed using :ghc-flag:`-plugin-package ⟨pkg⟩`
+    options.
 
 At the moment, the only way to specify a dependency on a plugin
 in Cabal is to put it in ``build-depends`` (which uses the conventional
-:ghc-flag:`-package-id` flag); however, in the future there
+:ghc-flag:`-package-id ⟨unit-id⟩` flag); however, in the future there
 will be a separate field for specifying plugin dependencies specifically.
 
 .. _writing-compiler-plugins:
@@ -577,7 +576,7 @@ A frontend plugin allows you to add new major modes to GHC.  You may prefer
 this over a traditional program which calls the GHC API, as GHC manages a lot
 of parsing flags and administrative nonsense which can be difficult to
 manage manually.  To load a frontend plugin exported by ``Foo.FrontendPlugin``,
-we just invoke GHC with the :ghc-flag:`--frontend` flag as follows:
+we just invoke GHC with the :ghc-flag:`--frontend ⟨module⟩` flag as follows:
 
 .. code-block:: none
 
index 684435c..c40b623 100644 (file)
@@ -335,12 +335,12 @@ reliably re-initialise after this has happened; see :ref:`infelicities-ffi`.
     will try to link to the ``Main`` Haskell module.
 
 To use ``+RTS`` flags with ``hs_init()``, we have to modify the example
-slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags
-(see :ref:`options-linker`), and the :ghc-flag:`-rtsopts`
-link-time flag overrides this. However, :ghc-flag:`-rtsopts` has no effect when
-:ghc-flag:`-no-hs-main` is in use (and the same goes for :ghc-flag:`-with-rtsopts`). To
-set these options we have to call a GHC-specific API instead of
-``hs_init()``:
+slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags (see
+:ref:`options-linker`), and the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
+link-time flag overrides this. However, :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
+has no effect when :ghc-flag:`-no-hs-main` is in use (and the same goes for
+:ghc-flag:`-with-rtsopts=⟨opts⟩`). To set these options we have to call a
+GHC-specific API instead of ``hs_init()``:
 
 .. code-block:: c
 
@@ -548,7 +548,7 @@ single Haskell thread, and possibly also use a bound thread (see
 
 Note that foreign calls made by different Haskell threads may execute in
 *parallel*, even when the ``+RTS -N`` flag is not being used
-(:ref:`parallel-options`). The :rts-flag:`-N` flag controls parallel
+(:ref:`parallel-options`). The :rts-flag:`-N ⟨x⟩` flag controls parallel
 execution of Haskell threads, but there may be an arbitrary number of
 foreign calls in progress at any one time, regardless of the ``+RTS -N``
 value.
index 2d27c26..8405af1 100644 (file)
@@ -1133,14 +1133,14 @@ IO ()``, and it works by converting the value to ``String`` using ``show``.
 This is not ideal in certain cases, like when the output is long, or
 contains strings with non-ascii characters.
 
-The :ghc-flag:`-interactive-print` flag allows to specify any function of type
-``C a => a -> IO ()``, for some constraint ``C``, as the function for
-printing evaluated expressions. The function can reside in any loaded
-module or any registered package, but only when it resides in a registered
-package will it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`,
+The :ghc-flag:`-interactive-print ⟨expr⟩` flag allows to specify any function
+of type ``C a => a -> IO ()``, for some constraint ``C``, as the function for
+printing evaluated expressions. The function can reside in any loaded module or
+any registered package, but only when it resides in a registered package will
+it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`,
 :ghci-cmd:`:reload` or, :ghci-cmd:`:set`.
 
-.. ghc-flag:: -interactive-print <expr>
+.. ghc-flag:: -interactive-print ⟨expr⟩
 
     Set the function used by GHCi to print evaluation results. Expression
     must be of type ``C a => a -> IO ()``.
@@ -1172,8 +1172,8 @@ will start an interactive session where values with be printed using
 A custom pretty printing function can be used, for example, to format
 tree-like and nested structures in a more readable way.
 
-The :ghc-flag:`-interactive-print` flag can also be used when running GHC in
-``-e mode``:
+The :ghc-flag:`-interactive-print ⟨expr⟩` flag can also be used when running
+GHC in ``-e mode``:
 
 .. code-block:: none
 
@@ -1729,7 +1729,7 @@ The history is only available when using :ghci-cmd:`:trace`; the reason for this
 is we found that logging each breakpoint in the history cuts performance
 by a factor of 2 or more.
 
-.. ghc-flag:: -fghci-hist-size
+.. ghc-flag:: -fghci-hist-size=⟨n⟩
 
     :default: 50
 
@@ -1961,7 +1961,7 @@ to specify any extra flags at all: they will be automatically loaded the
 first time they are needed.
 
 For hidden packages, however, you need to request the package be loaded
-by using the :ghc-flag:`-package` flag:
+by using the :ghc-flag:`-package ⟨pkg⟩` flag:
 
 .. code-block:: none
 
@@ -1999,7 +1999,7 @@ On systems with ``.so``-style shared libraries, the actual library
 loaded will the ``liblib.so``. GHCi searches the following places for
 libraries, in this order:
 
--  Paths specified using the :ghc-flag:`-L` command-line option,
+-  Paths specified using the :ghc-flag:`-L ⟨dir⟩` command-line option,
 
 -  the standard library search path for your system, which on some
    systems may be overridden by setting the :envvar:`LD_LIBRARY_PATH`
@@ -2321,7 +2321,7 @@ commonly used commands.
     Display the history of evaluation steps. With a number, displays
     that many steps (default: 20). For use with :ghci-cmd:`:trace`; see
     :ref:`tracing`. To set the number of history entries stored by GHCi,
-    use the :ghc-flag:`-fghci-hist-size` flag.
+    use the :ghc-flag:`-fghci-hist-size=⟨n⟩` flag.
 
 .. ghci-cmd:: :info;[!] ⟨name⟩
 
@@ -2585,7 +2585,7 @@ commonly used commands.
     Sets the string to be used as the continuation prompt (used when
     using the :ghci-cmd:`:{` command) in GHCi.
 
-.. ghci-cmd:: :set prompt-function; <prompt-function>
+.. ghci-cmd:: :set prompt-function; ⟨prompt-function⟩
 
     .. index::
        single: GHCi prompt function; setting
@@ -2598,7 +2598,7 @@ commonly used commands.
     more information). The second arguments is the line number (as referenced
     in compiler  messages) of the current prompt.
 
-.. ghci-cmd:: :set prompt-cont-function; <prompt-function>
+.. ghci-cmd:: :set prompt-cont-function; ⟨prompt-function⟩
 
    Sets the function to be used for the continuation prompt (used when
    using the :ghci-cmd:`:{` command) displaying in GHCi.
@@ -2911,9 +2911,9 @@ option, you can set the reverse option:
 :ref:`flag-reference` lists the reverse for each option where
 applicable.
 
-Certain static options (:ghc-flag:`-package`, :ghc-flag:`-I`, :ghc-flag:`-i`,
-and :ghc-flag:`-l` in particular) will also work, but some may not take effect
-until the next reload.
+Certain static options (:ghc-flag:`-package ⟨pkg⟩`, :ghc-flag:`-I⟨dir⟩`,
+:ghc-flag:`-i⟨dir⟩[:⟨dir⟩]*`, and :ghc-flag:`-l ⟨lib⟩` in particular) will also
+work, but some may not take effect until the next reload.
 
 .. index::
    single: static; options
@@ -3156,8 +3156,8 @@ using messages over a pipe.
     GHCi debugger, so breakpoints and single-stepping don't work with
     :ghc-flag:`-fexternal-interpreter`.
 
-    See also the :ghc-flag:`-pgmi` (:ref:`replacing-phases`) and :ghc-flag:`-opti`
-    (:ref:`forcing-options-through`) flags.
+    See also the :ghc-flag:`-pgmi ⟨cmd⟩` (:ref:`replacing-phases`) and
+    :ghc-flag:`-opti ⟨option⟩` (:ref:`forcing-options-through`) flags.
 
 Why might we want to do this?  The main reason is that the RTS running
 the interpreted code can be a different flavour (profiling or
index 7953067..78b3992 100644 (file)
@@ -5912,7 +5912,7 @@ Condition (described in :ref:`instance-termination`) are lifted.
 Termination is still ensured by having a fixed-depth recursion stack. If
 you exceed the stack depth you get a sort of backtrace, and the
 opportunity to increase the stack depth with
-``-freduction-depth=``\ *N*. However, if you should exceed the default
+``-freduction-depth=⟨n⟩``. However, if you should exceed the default
 reduction depth limit, it is probably best just to disable depth
 checking, with ``-freduction-depth=0``. The exact depth your program
 requires depends on minutiae of your code, and it may change between
@@ -10033,7 +10033,7 @@ Impredicative polymorphism
 
 .. ghc-flag:: -XImpredicativeTypes
 
-    :implies: :ghc-flag:`-RankNTypes`
+    :implies: :ghc-flag:`-XRankNTypes`
 
     Allow impredicative polymorphic types.
 
@@ -11124,17 +11124,17 @@ non-trivial program, you may be interested in combining this with the
 :ghc-flag:`-ddump-to-file` flag (see :ref:`dumping-output`. For each file using
 Template Haskell, this will show the output in a ``.dump-splices`` file.
 
-The flag :ghc-flag:`-dth-dec-file` shows the expansions of all top-level TH
-declaration splices, both typed and untyped, in the file :file:`M.th.hs`
-where M is the name of the module being compiled. Note that other types
-of splices (expressions, types, and patterns) are not shown. Application
-developers can check this into their repository so that they can grep
-for identifiers that were defined in Template Haskell. This is similar
-to using :ghc-flag:`-ddump-to-file` with :ghc-flag:`-ddump-splices` but it always
+The flag :ghc-flag:`-dth-dec-file=⟨file⟩` shows the expansions of all top-level
+TH declaration splices, both typed and untyped, in the file :file:`M.th.hs`
+where M is the name of the module being compiled. Note that other types of
+splices (expressions, types, and patterns) are not shown. Application
+developers can check this into their repository so that they can grep for
+identifiers that were defined in Template Haskell. This is similar to using
+:ghc-flag:`-ddump-to-file` with :ghc-flag:`-ddump-splices` but it always
 generates a file instead of being coupled to :ghc-flag:`-ddump-to-file`. The
-format is also different: it does not show code from the original file,
-instead it only shows generated code and has a comment for the splice
-location of the original file.
+format is also different: it does not show code from the original file, instead
+it only shows generated code and has a comment for the splice location of the
+original file.
 
 Below is a sample output of :ghc-flag:`-ddump-splices` ::
 
@@ -11145,7 +11145,7 @@ Below is a sample output of :ghc-flag:`-ddump-splices` ::
       foo :: Int -> Int
       foo x = (x + 1)
 
-Below is the output of the same sample using :ghc-flag:`-dth-dec-file` ::
+Below is the output of the same sample using :ghc-flag:`-dth-dec-file=⟨file⟩` ::
 
     -- TH_pragma.hs:(6,4)-(8,26): Splicing declarations
     foo :: Int -> Int
@@ -11247,15 +11247,15 @@ Fortunately GHC provides two workarounds.
 
 The first option is to compile the program twice:
 
-1. Compile the program or library first the normal way, without :ghc-flag:`-prof`.
+1. Compile the program or library first the normal way, without
+   :ghc-flag:`-prof`.
 
-2. Then compile it again with :ghc-flag:`-prof`, and additionally use ``-osuf p_o``
-   to name the object files differently (you can
-   choose any suffix that isn't the normal object suffix here). GHC will
-   automatically load the object files built in the first step when
-   executing splice expressions. If you omit the :ghc-flag:`-osuf` flag when
-   building with :ghc-flag:`-prof` and Template Haskell is used, GHC will emit
-   an error message.
+2. Then compile it again with :ghc-flag:`-prof`, and additionally use ``-osuf
+   p_o`` to name the object files differently (you can choose any suffix that
+   isn't the normal object suffix here). GHC will automatically load the object
+   files built in the first step when executing splice expressions. If you omit
+   the :ghc-flag:`-osuf ⟨suffix⟩` flag when building with :ghc-flag:`-prof` and
+   Template Haskell is used, GHC will emit an error message.
 
    .. index::
       single : -osuf; using with profiling
@@ -13537,7 +13537,7 @@ From a semantic point of view:
 -  Rules are enabled (that is, used during optimisation) by the
    :ghc-flag:`-fenable-rewrite-rules` flag. This flag is implied by
    :ghc-flag:`-O`, and may be switched off (as usual) by
-   :ghc-flag:`-fno-enable-rewrite-rules <-f-enable-rewrite-rules>`. (NB: enabling
+   :ghc-flag:`-fno-enable-rewrite-rules <-fenable-rewrite-rules>`. (NB: enabling
    :ghc-flag:`-fenable-rewrite-rules` without :ghc-flag:`-O` may not do what you
    expect, though, because without :ghc-flag:`-O` GHC ignores all optimisation
    information in interface files; see :ghc-flag:`-fignore-interface-pragmas`).
index 71059f1..3ed9455 100644 (file)
@@ -179,21 +179,20 @@ The GHC command line options that control packages are:
 
 .. ghc-flag:: -package-id ⟨unit-id⟩
 
-    Exposes a package like :ghc-flag:`-package`, but the package is named by its
-    unit ID (i.e. the value of ``id`` in its entry in the installed
-    package database, also previously known as an installed package ID)
-    rather than by name. This is a more robust way
-    to name packages, and can be used to select packages that would
-    otherwise be shadowed. Cabal passes ``-package-id`` flags to GHC.
-    ``-package-id`` supports thinning and renaming described in
-    :ref:`package-thinning-and-renaming`.
+    Exposes a package like :ghc-flag:`-package ⟨pkg⟩`, but the package is named
+    by its unit ID (i.e. the value of ``id`` in its entry in the installed
+    package database, also previously known as an installed package ID) rather
+    than by name. This is a more robust way to name packages, and can be used
+    to select packages that would otherwise be shadowed. Cabal passes
+    ``-package-id`` flags to GHC.  ``-package-id`` supports thinning and
+    renaming described in :ref:`package-thinning-and-renaming`.
 
 .. ghc-flag:: -hide-all-packages
 
     Ignore the exposed flag on installed packages, and hide them all by
     default. If you use this flag, then any packages you require
     (including ``base``) need to be explicitly exposed using
-    :ghc-flag:`-package` options.
+    :ghc-flag:`-package ⟨pkg⟩` options.
 
     This is a good way to insulate your program from differences in the
     globally exposed packages, and being explicit about package
@@ -202,7 +201,7 @@ The GHC command line options that control packages are:
 
 .. ghc-flag:: -hide-package ⟨pkg⟩
 
-    This option does the opposite of :ghc-flag:`-package`: it causes the
+    This option does the opposite of :ghc-flag:`-package ⟨pkg⟩`: it causes the
     specified package to be hidden, which means that none of its modules
     will be available for import by Haskell ``import`` directives.
 
@@ -215,11 +214,11 @@ The GHC command line options that control packages are:
     Causes the compiler to behave as if package ⟨pkg⟩, and any packages
     that depend on ⟨pkg⟩, are not installed at all.
 
-    Saying ``-ignore-package ⟨pkg⟩`` is the same as giving :ghc-flag:`-hide-package`
-    flags for ⟨pkg⟩ and all the packages that depend on ⟨pkg⟩. Sometimes
-    we don't know ahead of time which packages will be installed that
-    depend on ⟨pkg⟩, which is when the :ghc-flag:`-ignore-package` flag can be
-    useful.
+    Saying ``-ignore-package ⟨pkg⟩`` is the same as giving
+    :ghc-flag:`-hide-package ⟨pkg⟩` flags for ⟨pkg⟩ and all the packages that
+    depend on ⟨pkg⟩. Sometimes we don't know ahead of time which packages will
+    be installed that depend on ⟨pkg⟩, which is when the
+    :ghc-flag:`-ignore-package ⟨pkg⟩` flag can be useful.
 
 .. ghc-flag:: -no-auto-link-packages
 
@@ -239,26 +238,26 @@ The GHC command line options that control packages are:
 
     This option causes the install package ⟨pkg⟩ to be both exposed and
     trusted by GHC. This command functions in a very similar way
-    to the :ghc-flag:`-package` command but in addition sets the selected
+    to the :ghc-flag:`-package ⟨pkg⟩` command but in addition sets the selected
     packages to be trusted by GHC, regardless of the contents of the
     package database. (see :ref:`safe-haskell`).
 
 .. ghc-flag:: -distrust ⟨pkg⟩
 
     This option causes the install package ⟨pkg⟩ to be both exposed and
-    distrusted by GHC. This command functions in a very similar
-    way to the :ghc-flag:`-package` command but in addition sets the selected
-    packages to be distrusted by GHC, regardless of the contents of the
-    package database. (see :ref:`safe-haskell`).
+    distrusted by GHC. This command functions in a very similar way to the
+    :ghc-flag:`-package ⟨pkg⟩` command but in addition sets the selected
+    packages to be distrusted by GHC, regardless of the contents of the package
+    database. (see :ref:`safe-haskell`).
 
 .. ghc-flag:: -distrust-all
 
     Ignore the trusted flag on installed packages, and distrust them by
     default. If you use this flag and Safe Haskell then any packages you
-    require to be trusted (including ``base``) need to be explicitly
-    trusted using :ghc-flag:`-trust` options. This option does not change the
-    exposed/hidden status of a package, so it isn't equivalent to
-    applying :ghc-flag:`-distrust` to all packages on the system. (see
+    require to be trusted (including ``base``) need to be explicitly trusted
+    using :ghc-flag:`-trust ⟨pkg⟩` options. This option does not change the
+    exposed/hidden status of a package, so it isn't equivalent to applying
+    :ghc-flag:`-distrust ⟨pkg⟩` to all packages on the system. (see
     :ref:`safe-haskell`).
 
 .. _package-main:
@@ -266,10 +265,10 @@ The GHC command line options that control packages are:
 The ``main`` package
 --------------------
 
-Every complete Haskell program must define ``main`` in module ``Main``
-in package ``main``. Omitting the :ghc-flag:`-this-unit-id` flag compiles
-code for package ``main``. Failure to do so leads to a somewhat obscure
-link-time error of the form:
+Every complete Haskell program must define ``main`` in module ``Main`` in
+package ``main``. Omitting the :ghc-flag:`-this-unit-id ⟨unit-id⟩` flag
+compiles code for package ``main``. Failure to do so leads to a somewhat
+obscure link-time error of the form:
 
 .. code-block:: none
 
@@ -308,8 +307,8 @@ When incorporating packages from multiple sources, you may end up in a
 situation where multiple packages publish modules with the same name.
 Previously, the only way to distinguish between these modules was to use
 :ref:`package-qualified-imports`. However, since GHC 7.10, the
-:ghc-flag:`-package` flags (and their variants) have been extended to allow a
-user to explicitly control what modules a package brings into scope, by
+:ghc-flag:`-package ⟨pkg⟩` flags (and their variants) have been extended to
+allow a user to explicitly control what modules a package brings into scope, by
 analogy to the import lists that users can attach to module imports.
 
 The basic syntax is that instead of specifying a package name P to the
@@ -375,10 +374,10 @@ stack. Several command line options described below can further manipulate this
 initial stack. You can see GHC's effective package database stack by running
 GHC with the :ghc-flag:`-v` flag.
 
-This stack structure means that the order of :ghc-flag:`-package-db` flags or
-:envvar:`GHC_PACKAGE_PATH` is important.  Each substack of the stack
-must be well formed (packages in databases on top of the stack can refer
-to packages below, but not vice versa).
+This stack structure means that the order of :ghc-flag:`-package-db ⟨file⟩`
+flags or :envvar:`GHC_PACKAGE_PATH` is important.  Each substack of the stack
+must be well formed (packages in databases on top of the stack can refer to
+packages below, but not vice versa).
 
 *Package shadowing:* When multiple package databases are in use it
 is possible, though rarely, that the same installed package id is present in
@@ -516,8 +515,8 @@ command line arguments to ``ghc``:
     -package-id id_n
 
 Note the implicit :ghc-flag:`-hide-all-packages` and the fact that it is
-:ghc-flag:`-package-id`, not :ghc-flag:`-package`. This is because the
-environment specifies precisely which packages should be visible.
+:ghc-flag:`-package-id ⟨unit-id⟩`, not :ghc-flag:`-package ⟨pkg⟩`. This is
+because the environment specifies precisely which packages should be visible.
 
 Note that for the ``package-db`` directive, if a relative path is given it
 must be relative to the location of the package environment file.
@@ -530,10 +529,10 @@ must be relative to the location of the package environment file.
 In order, ``ghc`` will look for the package environment in the following
 locations:
 
--  File ⟨file⟩ if you pass the option :ghc-flag:`-package-env file`.
+-  File ⟨file⟩ if you pass the option :ghc-flag:`-package-env ⟨file⟩|⟨name⟩`.
 
 -  File ``$HOME/.ghc/arch-os-version/environments/name`` if you pass the
-   option ``-package-env name``.
+   option ``-package-env ⟨name⟩``.
 
 -  File ⟨file⟩ if the environment variable ``GHC_ENVIRONMENT`` is set to
    ⟨file⟩.
@@ -667,10 +666,11 @@ Package management (the ``ghc-pkg`` command)
    single: packages; management
 
 The :command:`ghc-pkg` tool is for querying and modifying package databases. To
-see what package databases are in use, use ``ghc-pkg list``. The stack
-of databases that :command:`ghc-pkg` knows about can be modified using the
+see what package databases are in use, use ``ghc-pkg list``. The stack of
+databases that :command:`ghc-pkg` knows about can be modified using the
 :envvar:`GHC_PACKAGE_PATH` environment variable (see :ref:`ghc-package-path`,
-and using :ghc-flag:`-package-db` options on the :command:`ghc-pkg` command line.
+and using :ghc-flag:`-package-db ⟨file⟩` options on the :command:`ghc-pkg`
+command line.
 
 When asked to modify a database, ``ghc-pkg`` modifies the global
 database by default. Specifying ``--user`` causes it to act on the user
index f35ba1b..831ace4 100644 (file)
@@ -161,7 +161,7 @@ Options affecting the C pre-processor
     large system with significant doses of conditional compilation, you
     really shouldn't need it.
 
-.. ghc-flag:: -D <symbol>[=<value>]
+.. ghc-flag:: -D⟨symbol⟩[=⟨value⟩]
 
     Define macro ⟨symbol⟩ in the usual way. NB: does *not* affect ``-D``
     macros passed to the C compiler when compiling with :ghc-flag:`-fvia-C`! For
@@ -170,11 +170,11 @@ Options affecting the C pre-processor
     When no value is given, the value is taken to be ``1``. For instance,
     ``-DUSE_MYLIB`` is equivalent to ``-DUSE_MYLIB=1``.
 
-.. ghc-flag:: -U ⟨symbol⟩
+.. ghc-flag:: -U⟨symbol⟩
 
     Undefine macro ⟨symbol⟩ in the usual way.
 
-.. ghc-flag:: -I ⟨dir⟩
+.. ghc-flag:: -I⟨dir⟩
 
     Specify a directory in which to look for ``#include`` files, in the
     usual C way.
@@ -376,16 +376,16 @@ Options affecting a Haskell pre-processor
     stripped away and (possibly) the C pre-processor has washed the
     Haskell input.
 
-    Use :ghc-flag:`-pgmF` to select the program to use as the preprocessor.
-    When invoked, the ⟨cmd⟩ pre-processor is given at least three
-    arguments on its command-line: the first argument is the name of the
-    original source file, the second is the name of the file holding the
-    input, and the third is the name of the file where ⟨cmd⟩ should
-    write its output to.
+    Use :ghc-flag:`-pgmF ⟨cmd⟩` to select the program to use as the
+    preprocessor.  When invoked, the ⟨cmd⟩ pre-processor is given at least
+    three arguments on its command-line: the first argument is the name of the
+    original source file, the second is the name of the file holding the input,
+    and the third is the name of the file where ⟨cmd⟩ should write its output
+    to.
 
     Additional arguments to the pre-processor can be passed in using the
-    :ghc-flag:`-optF` option. These are fed to ⟨cmd⟩ on the command line after
-    the three standard input and output arguments.
+    :ghc-flag:`-optF ⟨option⟩` option. These are fed to ⟨cmd⟩ on the command
+    line after the three standard input and output arguments.
 
     An example of a pre-processor is to convert your source files to the
     input encoding that GHC expects, i.e. create a script ``convert.sh``
@@ -540,12 +540,12 @@ for example).
 .. ghc-flag:: -staticlib
 
     Link all passed files into a static library suitable for linking.
-    To control the name, use the :ghc-flag:`-o` ⟨name⟩ option
+    To control the name, use the :ghc-flag:`-o ⟨file⟩` option
     as usual. The default name is ``liba.a``.
 
 .. ghc-flag:: -L ⟨dir⟩
 
-    Where to find user-supplied libraries… Prepend the directory ⟨dir⟩
+    Where to f ind user-supplied libraries… Prepend the directory ⟨dir⟩
     to the library directories path.
 
 .. ghc-flag:: -framework-path ⟨dir⟩
@@ -601,11 +601,11 @@ for example).
     might be an ELF DSO, a Windows DLL, or a Mac OS dylib. GHC hides the
     operating system details beneath this uniform flag.
 
-    The flags :ghc-flag:`-dynamic` and :ghc-flag:`-static` control whether the resulting
-    shared object links statically or dynamically to Haskell package
-    libraries given as :ghc-flag:`-package` option. Non-Haskell libraries are
-    linked as gcc would regularly link it on your system, e.g. on most
-    ELF system the linker uses the dynamic libraries when found.
+    The flags :ghc-flag:`-dynamic` and :ghc-flag:`-static` control whether the
+    resulting shared object links statically or dynamically to Haskell package
+    libraries given as :ghc-flag:`-package ⟨pkg⟩` option. Non-Haskell libraries
+    are linked as gcc would regularly link it on your system, e.g. on most ELF
+    system the linker uses the dynamic libraries when found.
 
     Object files linked into shared objects must be compiled with
     :ghc-flag:`-fPIC`, see :ref:`options-codegen`
@@ -673,11 +673,12 @@ for example).
     ``Main`` module present (normally the compiler will not attempt
     linking when there is no ``Main``).
 
-    The flags :ghc-flag:`-rtsopts` and :ghc-flag:`-with-rtsopts` have no effect when
-    used with :ghc-flag:`-no-hs-main`, because they are implemented by changing
-    the definition of ``main`` that GHC generates. See
-    :ref:`using-own-main` for how to get the effect of :ghc-flag:`-rtsopts` and
-    :ghc-flag:`-with-rtsopts` when using your own ``main``.
+    The flags :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` and
+    :ghc-flag:`-with-rtsopts=⟨opts⟩` have no effect when used with
+    :ghc-flag:`-no-hs-main`, because they are implemented by changing the
+    definition of ``main`` that GHC generates. See :ref:`using-own-main` for
+    how to get the effect of :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` and
+    :ghc-flag:`-with-rtsopts=⟨opts⟩` when using your own ``main``.
 
 .. ghc-flag:: -debug
 
@@ -699,7 +700,7 @@ for example).
 
     The threaded runtime system provides the following benefits:
 
-    -  It enables the :rts-flag:`-N` RTS option to be used,
+    -  It enables the :rts-flag:`-N ⟨x⟩` RTS option to be used,
        which allows threads to run in parallelparallelism on a
        multiprocessormultiprocessorSMP or multicoremulticore machine.
        See :ref:`using-smp`.
@@ -722,7 +723,9 @@ for example).
     :ghc-flag:`-eventlog` can be used with :ghc-flag:`-threaded`. It is implied by
     :ghc-flag:`-debug`.
 
-.. ghc-flag:: -rtsopts
+.. ghc-flag:: -rtsopts[=⟨none|some|all⟩]
+
+    :default: all
 
     This option affects the processing of RTS control options given
     either on the command line or via the :envvar:`GHCRTS` environment
@@ -754,7 +757,7 @@ for example).
     Note that ``-rtsopts`` has no effect when used with :ghc-flag:`-no-hs-main`;
     see :ref:`using-own-main` for details.
 
-.. ghc-flag:: -with-rtsopts
+.. ghc-flag:: -with-rtsopts=⟨opts⟩
 
     This option allows you to set the default RTS options at link-time.
     For example, ``-with-rtsopts="-H128m"`` sets the default heap size
@@ -769,12 +772,12 @@ for example).
 
 .. ghc-flag:: -no-rtsopts-suggestions
 
-    This option disables RTS suggestions about linking with :ghc-flag:`-rtsopts`
-    when they are not available. These suggestions would be unhelpful if
-    the users have installed Haskell programs through their package
-    managers. With this option enabled, these suggestions will not
-    appear. It is recommended for people distributing binaries to build
-    with either ``-rtsopts`` or ``-no-rtsopts-suggestions``.
+    This option disables RTS suggestions about linking with
+    :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` when they are not available. These
+    suggestions would be unhelpful if the users have installed Haskell programs
+    through their package managers. With this option enabled, these suggestions
+    will not appear. It is recommended for people distributing binaries to
+    build with either ``-rtsopts`` or ``-no-rtsopts-suggestions``.
 
 .. ghc-flag:: -fno-gen-manifest
 
@@ -812,16 +815,15 @@ for example).
     .. index::
        single: windres
 
-    The manifest file that GHC generates when linking a binary on
-    Windows is also embedded in the executable itself, by default. This
-    means that the binary can be distributed without having to supply
-    the manifest file too. The embedding is done by running
-    :command:`windres`; to see exactly what GHC does to embed the
-    manifest, use the :ghc-flag:`-v` flag. A GHC installation comes with its own
-    copy of ``windres`` for this reason.
+    The manifest file that GHC generates when linking a binary on Windows is
+    also embedded in the executable itself, by default. This means that the
+    binary can be distributed without having to supply the manifest file too.
+    The embedding is done by running :command:`windres`; to see exactly what
+    GHC does to embed the manifest, use the :ghc-flag:`-v` flag. A GHC
+    installation comes with its own copy of ``windres`` for this reason.
 
-    See also :ghc-flag:`-pgmwindres` (:ref:`replacing-phases`) and
-    :ghc-flag:`-optwindres` (:ref:`forcing-options-through`).
+    See also :ghc-flag:`-pgmwindres ⟨cmd⟩` (:ref:`replacing-phases`) and
+    :ghc-flag:`-optwindres ⟨option⟩` (:ref:`forcing-options-through`).
 
 .. ghc-flag:: -fno-shared-implib
 
@@ -838,7 +840,7 @@ for example).
     :ghc-flag:`-fno-shared-implib` flag to disable the creation of the import
     library entirely.
 
-.. ghc-flag:: -dylib-install-name <path>
+.. ghc-flag:: -dylib-install-name ⟨path⟩
 
     On Darwin/OS X, dynamic libraries are stamped at build time with an
     "install name", which is the ultimate install path of the library
index cf345ed..0a4ba09 100644 (file)
@@ -402,8 +402,9 @@ enclosed between ``+RTS ... -RTS`` as usual):
        single: time profile
 
     The :rts-flag:`-p` option produces a standard *time profile* report. It is
-    written into the file :file:`<stem>.prof`; the stem is taken to be the program
-    name by default, but can be overridden by the :rts-flag:`-po` flag.
+    written into the file :file:`<stem>.prof`; the stem is taken to be the
+    program name by default, but can be overridden by the :rts-flag:`-po
+    ⟨stem⟩` flag.
 
     The :rts-flag:`-P` option produces a more detailed report containing the
     actual time and allocation data as well. (Not used much.)
@@ -418,19 +419,36 @@ enclosed between ``+RTS ... -RTS`` as usual):
 
 .. rts-flag:: -po ⟨stem⟩
 
-    The :rts-flag:`-po` option overrides the stem used to form the output file
-    paths for the cost-centre profiler (see :rts-flag:`-p` and :rts-flag:`-pj`
-    flags above) and heap profiler (see :rts-flag:`-h`).
+    The :rts-flag:`-po ⟨stem⟩` option overrides the stem used to form the
+    output file paths for the cost-centre profiler (see :rts-flag:`-p` and
+    :rts-flag:`-pj` flags above) and heap profiler (see :rts-flag:`-h`).
 
     For instance, running a program with ``+RTS -h -p -pohello-world`` would
     produce a heap profile named :file:`hello-world.hp` and a cost-centre
     profile named :file:`hello-world.prof`.
 
-.. rts-flag:: -V <secs>
+.. rts-flag:: -V ⟨secs⟩
+
+    Sets the interval that the RTS clock ticks at, which is also the sampling
+    interval of the time and allocation profile. The default is 0.02 seconds.
+    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 ⟨secs⟩` 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 ⟨s⟩` or :rts-flag:`-i
+    ⟨secs⟩` options. However, setting :rts-flag:`-V ⟨secs⟩` 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.
 
-    Sets the interval that the RTS clock ticks at, which is also the
-    sampling interval of the time and allocation profile. The default is
-    0.02 seconds.
 
 .. rts-flag:: -xc
 
@@ -456,7 +474,7 @@ has the following properties,
     The command line arguments passed to the runtime system
 ``initial_capabilities`` (integral number)
     How many capabilities the program was started with (e.g. using the
-    :rts-flag:`-N` option). Note that the number of capabilities may change
+    :rts-flag:`-N ⟨x⟩` option). Note that the number of capabilities may change
     during execution due to the ``setNumCapabilities`` function.
 ``total_time`` (number)
     The total wall time of the program's execution in seconds.
@@ -694,42 +712,42 @@ follows:
     The flags below are marked with ``:noindex:`` to avoid duplicate
     ID warnings from Sphinx.
 
-.. rts-flag:: -hc <name>
+.. rts-flag:: -hc ⟨name⟩
     :noindex:
 
     Restrict the profile to closures produced by cost-centre stacks with
     one of the specified cost centres at the top.
 
-.. rts-flag:: -hC <name>
+.. rts-flag:: -hC ⟨name⟩
     :noindex:
 
     Restrict the profile to closures produced by cost-centre stacks with
     one of the specified cost centres anywhere in the stack.
 
-.. rts-flag:: -hm <module>
+.. rts-flag:: -hm ⟨module⟩
     :noindex:
 
     Restrict the profile to closures produced by the specified modules.
 
-.. rts-flag:: -hd <desc>
+.. rts-flag:: -hd ⟨desc⟩
     :noindex:
 
     Restrict the profile to closures with the specified description
     strings.
 
-.. rts-flag:: -hy <type>
+.. rts-flag:: -hy ⟨type⟩
     :noindex:
 
     Restrict the profile to closures with the specified types.
 
-.. rts-flag:: -hr <cc>
+.. rts-flag:: -hr ⟨cc⟩
     :noindex:
 
     Restrict the profile to closures with retainer sets containing
     cost-centre stacks with one of the specified cost centres at the
     top.
 
-.. rts-flag:: -hb <bio>
+.. rts-flag:: -hb ⟨bio⟩
     :noindex:
 
     Restrict the profile to closures with one of the specified
@@ -750,7 +768,7 @@ doesn't currently support mixing the :rts-flag:`-hr` and :rts-flag:`-hb` options
 
 There are three more options which relate to heap profiling:
 
-.. rts-flag:: -i <secs>
+.. rts-flag:: -i ⟨secs⟩
 
     Set the profiling (sampling) interval to ⟨secs⟩ seconds (the default
     is 0.1 second). Fractions are allowed: for example ``-i0.2`` will
@@ -772,7 +790,7 @@ There are three more options which relate to heap profiling:
     “STACK” respectively when displaying the profile by closure
     description or type description.
 
-.. rts-flag:: -L <num>
+.. rts-flag:: -L ⟨num⟩
 
     Sets the maximum length of a cost-centre stack name in a heap
     profile. Defaults to 25.
@@ -809,9 +827,9 @@ to discover the full retainer set for each object, which can be quite
 slow. So we set a limit on the maximum size of a retainer set, where all
 retainer sets larger than the maximum retainer set size are replaced by
 the special set ``MANY``. The maximum set size defaults to 8 and can be
-altered with the :rts-flag:`-R` RTS option:
+altered with the :rts-flag:`-R ⟨size⟩` RTS option:
 
-.. rts-flag:: -R <size>
+.. rts-flag:: -R ⟨size⟩
 
     Restrict the number of elements in a retainer set to ⟨size⟩ (default
     8).
@@ -909,17 +927,16 @@ reasons for this:
    currently 2 extra words per heap object, which probably results in
    about a 30% overhead.
 
--  Garbage collection requires more memory than the actual residency.
-   The factor depends on the kind of garbage collection algorithm in
-   use: a major GC in the standard generation copying collector will
-   usually require 3L bytes of memory, where L is the amount of live
-   data. This is because by default (see the RTS :rts-flag:`-F` option) we
-   allow the old generation to grow to twice its size (2L) before
-   collecting it, and we require additionally L bytes to copy the live
-   data into. When using compacting collection (see the :rts-flag:`-c`
-   option), this is reduced to 2L, and can further be reduced by
-   tweaking the :rts-flag:`-F` option. Also add the size of the allocation area
-   (see :rts-flag:`-A`).
+-  Garbage collection requires more memory than the actual residency.  The
+   factor depends on the kind of garbage collection algorithm in use: a major GC
+   in the standard generation copying collector will usually require 3L bytes of
+   memory, where L is the amount of live data. This is because by default (see
+   the RTS :rts-flag:`-F ⟨factor⟩` option) we allow the old generation to grow
+   to twice its size (2L) before collecting it, and we require additionally L
+   bytes to copy the live data into. When using compacting collection (see the
+   :rts-flag:`-c` option), this is reduced to 2L, and can further be reduced by
+   tweaking the :rts-flag:`-F ⟨factor⟩` option. Also add the size of the
+   allocation area (see :rts-flag:`-A ⟨size⟩`).
 
 -  The stack isn't counted in the heap profile by default. See the
    RTS :rts-flag:`-xt` option.
@@ -976,7 +993,7 @@ The flags are:
     to use a big box instead. The ``-b`` option forces ``hp2ps`` to use
     a big box.
 
-.. option:: -e<float>[in|mm|pt]
+.. option:: -e⟨float⟩[in|mm|pt]
 
     Generate encapsulated PostScript suitable for inclusion in LaTeX
     documents. Usually, the PostScript graph is drawn in landscape mode
@@ -1004,7 +1021,7 @@ The flags are:
     necessary. No key is produced as it won't fit!. It is useful for
     creation time profiles with many bands.
 
-.. option:: -m<int>
+.. option:: -m⟨int⟩
 
     Normally a profile is limited to 20 bands with additional
     identifiers being grouped into an ``OTHER`` band. The ``-m`` flag
@@ -1029,7 +1046,7 @@ The flags are:
 
     Use a small box for the title.
 
-.. option:: -t<float>
+.. option:: -t⟨float⟩
 
     Normally trace elements which sum to a total of less than 1% of the
     profile are removed from the profile. The ``-t`` option allows this
@@ -1174,7 +1191,7 @@ Profiling Parallel and Concurrent Programs
 
 Combining :ghc-flag:`-threaded` and :ghc-flag:`-prof` is perfectly fine, and
 indeed it is possible to profile a program running on multiple processors with
-the RTS :rts-flag:`-N` option. [3]_
+the RTS :rts-flag:`-N ⟨x⟩` option. [3]_
 
 Some caveats apply, however. In the current implementation, a profiled
 program is likely to scale much less well than the unprofiled program,
index 3c606c9..5286784 100644 (file)
@@ -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`.
index 0c981d5..04ef591 100644 (file)
@@ -65,12 +65,12 @@ an object file, and an interface file.
 The object file, which normally ends in a ``.o`` suffix, contains the
 compiled code for the module.
 
-The interface file, which normally ends in a ``.hi`` suffix, contains
-the information that GHC needs in order to compile further modules that
-depend on this module. It contains things like the types of exported
-functions, definitions of data types, and so on. It is stored in a
-binary format, so don't try to read one; use the :ghc-flag:`--show-iface` option
-instead (see :ref:`hi-options`).
+The interface file, which normally ends in a ``.hi`` suffix, contains the
+information that GHC needs in order to compile further modules that depend on
+this module. It contains things like the types of exported functions,
+definitions of data types, and so on. It is stored in a binary format, so don't
+try to read one; use the :ghc-flag:`--show-iface ⟨file⟩` option instead (see
+:ref:`hi-options`).
 
 You should think of the object file and the interface file as a pair,
 since the interface file is in a sense a compiler-readable description
@@ -97,10 +97,10 @@ changed with the ``-osuf`` option).
    by slashes. GHC will silently create the necessary directory
    structure underneath ⟨dir⟩, if it does not already exist.
 
-The name of the interface file is derived using the same rules, except
-that the suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and
-the relevant options are :ghc-flag:`-hidir` and :ghc-flag:`-hisuf` instead of
-:ghc-flag:`-odir` and :ghc-flag:`-osuf` respectively.
+The name of the interface file is derived using the same rules, except that the
+suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and the relevant
+options are :ghc-flag:`-hidir ⟨dir⟩` and :ghc-flag:`-hisuf ⟨suffix⟩` instead of
+:ghc-flag:`-odir ⟨dir⟩` and :ghc-flag:`-osuf ⟨suffix⟩` respectively.
 
 For example, if GHC compiles the module ``A.B.C`` in the file
 ``src/A/B/C.hs``, with no ``-odir`` or ``-hidir`` flags, the interface
@@ -119,9 +119,9 @@ for the interface for module ``Main`` (because it is never imported). It
 is therefore possible to have several ``Main`` modules in separate
 source files in the same directory, and GHC will not get confused.
 
-In batch compilation mode, the name of the object file can also be
-overridden using the :ghc-flag:`-o` option, and the name of the interface file
-can be specified directly using the :ghc-flag:`-ohi` option.
+In batch compilation mode, the name of the object file can also be overridden
+using the :ghc-flag:`-o ⟨file⟩` option, and the name of the interface file can
+be specified directly using the :ghc-flag:`-ohi ⟨file⟩` option.
 
 .. _search-path:
 
@@ -286,7 +286,8 @@ Redirecting the compilation output(s)
 .. ghc-flag:: -outputdir ⟨dir⟩
 
     The ``-outputdir`` option is shorthand for the combination of
-    :ghc-flag:`-odir`, :ghc-flag:`-hidir`, :ghc-flag:`-stubdir` and :ghc-flag:`-dumpdir`.
+    :ghc-flag:`-odir ⟨dir⟩`, :ghc-flag:`-hidir ⟨dir⟩`, :ghc-flag:`-stubdir
+    ⟨dir⟩` and :ghc-flag:`-dumpdir ⟨dir⟩`.
 
 .. ghc-flag:: -osuf ⟨suffix⟩
               -hisuf ⟨suffix⟩
@@ -390,11 +391,11 @@ Redirecting temporary files
 .. index::
    single: temporary files; redirecting
 
-.. ghc-flag:: -tmpdir
+.. ghc-flag:: -tmpdir ⟨dir⟩
 
     If you have trouble because of running out of space in ``/tmp`` (or
     wherever your installation thinks temporary files should go), you
-    may use the ``-tmpdir <dir>``-tmpdir <dir> option option to specify an
+    may use the :ghc-flag:`-tmpdir ⟨dir⟩` option option to specify an
     alternate directory. For example, ``-tmpdir .`` says to put temporary files
     in the current working directory.
 
@@ -430,7 +431,7 @@ Other options related to interface files
     Dump to the file :file:`{M}.imports` (where ⟨M⟩ is the name of the module
     being compiled) a "minimal" set of import declarations. The
     directory where the ``.imports`` files are created can be controlled
-    via the :ghc-flag:`-dumpdir` option.
+    via the :ghc-flag:`-dumpdir ⟨dir⟩` option.
 
     You can safely replace all the import declarations in :file:`{M}.hs` with
     those found in its respective ``.imports`` file. Why would you want
@@ -732,7 +733,7 @@ to ``hs-boot`` files, but with some slight changes:
 - Unlike regular modules, the defined entities of
   a signature include not only those written in the local
   ``hsig`` file, but also those from inherited signatures
-  (as inferred from the :ghc-flag:`-package-id` flags).
+  (as inferred from the :ghc-flag:`-package-id ⟨unit-id⟩` flags).
   These entities are not considered in scope when typechecking
   the local ``hsig`` file, but are available for import by
   any module or signature which imports the signature.  The
@@ -1186,7 +1187,7 @@ generation are:
     ``.depend`` and then ``include`` the file ``.depend`` into
     ``Makefile``.
 
-.. ghc-flag:: -dep-suffix <suf>
+.. ghc-flag:: -dep-suffix ⟨suffix⟩
 
     Make dependencies that declare that files with suffix
     ``.<suf><osuf>`` depend on interface files with suffix
@@ -1197,7 +1198,7 @@ generation are:
     Note that you must provide at least one suffix; if you do not want a suffix
     then pass ``-dep-suffix ''``.
 
-.. ghc-flag:: --exclude-module=<file>
+.. ghc-flag:: --exclude-module=⟨file⟩
 
     Regard ``<file>`` as "stable"; i.e., exclude it from having
     dependencies on it.
@@ -1296,10 +1297,9 @@ creating an orphan module. Like any warning, you can switch the warning
 off with :ghc-flag:`-Wno-orphans <-Worphans>`, and :ghc-flag:`-Werror` will make
 the compilation fail if the warning is issued.
 
-You can identify an orphan module by looking in its interface file,
-``M.hi``, using the :ghc-flag:`--show-iface` :ref:`mode <modes>`. If there is a
-``[orphan module]`` on the first line, GHC considers it an orphan
-module.
+You can identify an orphan module by looking in its interface file, ``M.hi``,
+using the :ghc-flag:`--show-iface ⟨file⟩` :ref:`mode <modes>`. If there is a
+``[orphan module]`` on the first line, GHC considers it an orphan module.
 
 .. [1]
    This is a change in behaviour relative to 6.2 and earlier.
index c0c54f1..486df51 100644 (file)
@@ -212,14 +212,13 @@ paths. The unix tool ``readelf --dynamic`` is handy for inspecting the
 Mac OS X
 ~~~~~~~~
 
-The standard assumption on Darwin/Mac OS X is that dynamic libraries
-will be stamped at build time with an "install name", which is the full
-ultimate install path of the library file. Any libraries or executables
-that subsequently link against it (even if it hasn't been installed yet)
-will pick up that path as their runtime search location for it. When
-compiling with ghc directly, the install name is set by default to the
-location where it is built. You can override this with the
-:ghc-flag:`-dylib-install-name` option (which passes ``-install_name`` to the
-Apple linker). Cabal does this for you. It automatically sets the
-install name for dynamic libraries to the absolute path of the ultimate
-install location.
+The standard assumption on Darwin/Mac OS X is that dynamic libraries will be
+stamped at build time with an "install name", which is the full ultimate
+install path of the library file. Any libraries or executables that
+subsequently link against it (even if it hasn't been installed yet) will pick
+up that path as their runtime search location for it. When compiling with ghc
+directly, the install name is set by default to the location where it is built.
+You can override this with the :ghc-flag:`-dylib-install-name ⟨path⟩` option
+(which passes ``-install_name`` to the Apple linker). Cabal does this for you.
+It automatically sets the install name for dynamic libraries to the absolute
+path of the ultimate install location.
index 48958d6..6851536 100644 (file)
@@ -30,11 +30,11 @@ Use more memory:
     .. index::
        single: -H; RTS option
 
-    If it says you're using more than 20% of total time in garbage
-    collecting, then more memory might help: use the ``-H⟨size⟩`` (see
-    :rts-flag:`-H`) option. Increasing the default allocation area size used by
-    the compiler's RTS might also help: use the ``+RTS -A⟨size⟩ -RTS``
-    option (see :rts-flag:`-A`).
+    If it says you're using more than 20% of total time in garbage collecting,
+    then more memory might help: use the ``-H⟨size⟩`` (see :rts-flag:`-H
+    [⟨size⟩]`) option. Increasing the default allocation area size used by the
+    compiler's RTS might also help: use the ``+RTS -A⟨size⟩ -RTS`` option (see
+    :rts-flag:`-A ⟨size⟩`).
 
     .. index::
        single: -A⟨size⟩; RTS option
@@ -114,13 +114,13 @@ Optimise, using ``-O`` or ``-O2``:
 
 Compile via LLVM:
     The :ref:`LLVM code generator <llvm-code-gen>` can sometimes do a far
-    better job at producing fast code than the :ref:`native code
-    generator <native-code-gen>`. This is not universal and depends
-    on the code. Numeric heavy code seems to show the best improvement
-    when compiled via LLVM. You can also experiment with passing
-    specific flags to LLVM with the :ghc-flag:`-optlo` and :ghc-flag:`-optlc`
-    flags. Be careful though as setting these flags stops GHC from setting its
-    usual flags for the LLVM optimiser and compiler.
+    better job at producing fast code than the :ref:`native code generator
+    <native-code-gen>`. This is not universal and depends on the code. Numeric
+    heavy code seems to show the best improvement when compiled via LLVM. You
+    can also experiment with passing specific flags to LLVM with the
+    :ghc-flag:`-optlo ⟨option⟩` and :ghc-flag:`-optlc ⟨option⟩` flags. Be
+    careful though as setting these flags stops GHC from setting its usual
+    flags for the LLVM optimiser and compiler.
 
 Overloaded functions are not your friend:
     Haskell's overloading (using type classes) is elegant, neat, etc.,
@@ -149,7 +149,7 @@ Use ``SPECIALIZE`` pragmas:
 "But how do I know where overloading is creeping in?"
     A low-tech way: grep (search) your interface files for overloaded
     type signatures. You can view interface files using the
-    :ghc-flag:`--show-iface` option (see :ref:`hi-options`).
+    :ghc-flag:`--show-iface ⟨file⟩` option (see :ref:`hi-options`).
 
     .. code-block:: sh
 
@@ -303,13 +303,13 @@ Use unboxed arrays (``UArray``)
     ``Data.Array`` library.
 
 Use a bigger heap!
-    If your program's GC stats (:rts-flag:`-S` RTS option) indicate that
-    it's doing lots of garbage-collection (say, more than 20% of execution
+    If your program's GC stats (:rts-flag:`-S [⟨file⟩]` RTS option) indicate
+    that it's doing lots of garbage-collection (say, more than 20% of execution
     time), more memory might help — with the ``-H⟨size⟩`` or ``-A⟨size⟩`` RTS
     options (see :ref:`rts-options-gc`). As a rule of thumb, try setting
     ``-H⟨size⟩`` to the amount of memory you're willing to let your process
-    consume, or perhaps try passing :ghc-flag:`-H` without any argument to let GHC
-    calculate a value based on the amount of live data.
+    consume, or perhaps try passing :ghc-flag:`-H ⟨size⟩` without any argument
+    to let GHC calculate a value based on the amount of live data.
 
 Compact your data:
     The :compact-ref:`GHC.Compact <GHC-Compact.html>` module
index d62b811..f0236a3 100644 (file)
@@ -16,7 +16,7 @@ for that module.
 Optionally, the program may be linked with the :ghc-flag:`-threaded` option (see
 :ref:`options-linker`. This provides two benefits:
 
-- It enables the :rts-flag:`-N` to be used, which allows threads to run in
+- It enables the :rts-flag:`-N ⟨x⟩` to be used, which allows threads to run in
   parallelism on a multi-processor or multi-core machine. See :ref:`using-smp`.
 
 - If a thread makes a foreign call (and the call is not marked
@@ -31,7 +31,7 @@ programs:
 .. index::
    single: RTS options; concurrent
 
-.. rts-flag:: -C <s>
+.. rts-flag:: -C ⟨s⟩
 
     :default: 20 milliseconds
 
@@ -107,8 +107,8 @@ There are two ways to run a program on multiple processors: call
 ``Control.Concurrent.setNumCapabilities`` from your program, or use the
 RTS ``-N`` options.
 
-.. rts-flag:: -N <x>
-              -maxN <x>
+.. rts-flag:: -N ⟨x⟩
+              -maxN ⟨x⟩
 
     Use ⟨x⟩ simultaneous threads when running the program.
 
@@ -179,11 +179,11 @@ CPUs:
 Hints for using SMP parallelism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Add the :rts-flag:`-s` RTS option when running the program to see timing stats,
-which will help to tell you whether your program got faster by using
-more CPUs or not. If the user time is greater than the elapsed time,
-then the program used more than one CPU. You should also run the program
-without :rts-flag:`-N` for comparison.
+Add the :rts-flag:`-s [⟨file⟩]` RTS option when running the program to see
+timing stats, which will help to tell you whether your program got faster by
+using more CPUs or not. If the user time is greater than the elapsed time, then
+the program used more than one CPU. You should also run the program without
+:rts-flag:`-N ⟨x⟩` for comparison.
 
 The output of ``+RTS -s`` tells you how many "sparks" were created and
 executed during the run of the program (see :ref:`rts-options-gc`),
index 185e590..15916b2 100644 (file)
@@ -171,9 +171,11 @@ by saying ``-fno-wombat``.
     to their usage sites. It also inlines simple expressions like
     literals or registers.
 
-.. ghc-flag:: -fcpr-off
+.. ghc-flag:: -fcpr-anal
 
-    Switch off CPR analysis in the demand analyser.
+    :default: on
+
+    Turn on CPR analysis in the demand analyser.
 
 .. ghc-flag:: -fcse
 
@@ -343,7 +345,7 @@ by saying ``-fno-wombat``.
     a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for
     free variables rather than arguments.
 
-.. ghc-flag:: -fliberate-case-threshold=<n>
+.. ghc-flag:: -fliberate-case-threshold=⟨n⟩
 
     :default: 2000
 
@@ -357,7 +359,7 @@ by saying ``-fno-wombat``.
     self-recursive saturated tail calls into local jumps rather than
     function calls.
 
-.. ghc-flag:: -fmax-inline-alloc-size=<n>
+.. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩
 
     :default: 128
 
@@ -366,20 +368,20 @@ by saying ``-fno-wombat``.
     nursery block if they're no bigger than n bytes, ignoring GC overheap. This
     value should be quite a bit smaller than the block size (typically: 4096).
 
-.. ghc-flag:: -fmax-inline-memcpy-insn=<n>
+.. ghc-flag:: -fmax-inline-memcpy-insns=⟨n⟩
 
     :default: 32
 
     Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions.
 
-.. ghc-flag:: -fmax-inline-memset-insns=<n>
+.. ghc-flag:: -fmax-inline-memset-insns=⟨n⟩
 
     :default: 32
 
     Inline ``memset`` calls if they would generate no more than n pseudo
     instructions.
 
-.. ghc-flag:: -fmax-relevant-binds=<n>
+.. ghc-flag:: -fmax-relevant-binds=⟨n⟩
               -fno-max-relevant-bindings
 
     :default: 6
@@ -392,7 +394,7 @@ by saying ``-fno-wombat``.
     they may be numerous), but ``-fno-max-relevant-bindings`` includes
     them too.
 
-.. ghc-flag:: -fmax-valid-substitutions=<n>
+.. ghc-flag:: -fmax-valid-substitutions=⟨n⟩
               -fno-max-valid-substitutions
 
     :default: 6
@@ -402,20 +404,20 @@ by saying ``-fno-wombat``.
     set by this flag. Turning it off with
     ``-fno-max-valid-substitutions`` gives an unlimited number.
 
-.. ghc-flag:: -fmax-uncovered-patterns=<n>
+.. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩
 
     :default: 4
 
     Maximum number of unmatched patterns to be shown in warnings generated by
     :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`.
 
-.. ghc-flag:: -fmax-simplifier-iterations=<n>
+.. ghc-flag:: -fmax-simplifier-iterations=⟨n⟩
 
     :default: 4
 
     Sets the maximal number of iterations for the simplifier.
 
-.. ghc-flag:: -fmax-worker-args=<n>
+.. ghc-flag:: -fmax-worker-args=⟨n⟩
 
     :default: 10
 
@@ -497,13 +499,13 @@ by saying ``-fno-wombat``.
     as the :ghc-flag:`-fregs-graph` one but also enables iterative coalescing
     during register allocation.
 
-.. ghc-flag:: -fsimplifier-phases=<n>
+.. ghc-flag:: -fsimplifier-phases=⟨n⟩
 
     :default: 2
 
     Set the number of phases for the simplifier. Ignored with ``-O0``.
 
-.. ghc-flag:: -fsimpl-tick-factor=<n>
+.. ghc-flag:: -fsimpl-tick-factor=⟨n⟩
 
     :default: 100
 
@@ -597,14 +599,14 @@ by saying ``-fno-wombat``.
     beneficial; e.g. the argument might be given to some other function
     that can itself be specialised.
 
-.. ghc-flag:: -fspec-constr-count=<n>
+.. ghc-flag:: -fspec-constr-count=⟨n⟩
 
     :default: 3
 
     Set the maximum number of specialisations that will be created for
     any one function by the SpecConstr transformation.
 
-.. ghc-flag:: -fspec-constr-threshold=<n>
+.. ghc-flag:: -fspec-constr-threshold=⟨n⟩
 
     :default: 2000
 
@@ -757,7 +759,7 @@ by saying ``-fno-wombat``.
     Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only
     unbox strict fields which are "small".
 
-.. ghc-flag:: -funfolding-creation-threshold=<n>
+.. ghc-flag:: -funfolding-creation-threshold=⟨n⟩
 
     :default: 750
 
@@ -776,11 +778,11 @@ by saying ``-fno-wombat``.
     a. nothing larger than this will be inlined (unless it has an ``INLINE`` pragma)
     b. nothing larger than this will be spewed into an interface file.
 
-    Increasing this figure is more likely to result in longer compile
-    times than faster code. The :ghc-flag:`-funfolding-use-threshold` is more
+    Increasing this figure is more likely to result in longer compile times
+    than faster code. The :ghc-flag:`-funfolding-use-threshold=⟨n⟩` is more
     useful.
 
-.. ghc-flag:: -funfolding-dict-discount=<n>
+.. ghc-flag:: -funfolding-dict-discount=⟨n⟩
 
     :default: 30
 
@@ -790,7 +792,7 @@ by saying ``-fno-wombat``.
 
     How eager should the compiler be to inline dictionaries?
 
-.. ghc-flag:: -funfolding-fun-discount=<n>
+.. ghc-flag:: -funfolding-fun-discount=⟨n⟩
 
     :default: 60
 
@@ -800,7 +802,7 @@ by saying ``-fno-wombat``.
 
     How eager should the compiler be to inline functions?
 
-.. ghc-flag:: -funfolding-keeness-factor=<n>
+.. ghc-flag:: -funfolding-keeness-factor=⟨n⟩
 
     :default: 1.5
 
@@ -810,7 +812,7 @@ by saying ``-fno-wombat``.
 
     How eager should the compiler be to inline functions?
 
-.. ghc-flag:: -funfolding-use-threshold=<n>
+.. ghc-flag:: -funfolding-use-threshold=⟨n⟩
 
     :default: 60
 
@@ -825,10 +827,11 @@ by saying ``-fno-wombat``.
     minus any discounts that apply depending on the context into which
     the expression is to be inlined.
 
-    The difference between this and :ghc-flag:`-funfolding-creation-threshold`
-    is that this one determines if a function definition will be inlined
-    *at a call site*. The other option determines if a function
-    definition will be kept around at all for potential inlining.
+    The difference between this and
+    :ghc-flag:`-funfolding-creation-threshold=⟨n⟩` is that this one determines
+    if a function definition will be inlined *at a call site*. The other option
+    determines if a function definition will be kept around at all for
+    potential inlining.
 
 .. ghc-flag:: -fvectorisation-avoidance
 
index 9f10efb..ce2de5c 100644 (file)
@@ -104,7 +104,7 @@ to abort.
     Makes any warning into a fatal error. Useful so that you don't miss
     warnings when doing batch compilation.
 
-.. ghc-flag:: -Werror=<wflag>
+.. ghc-flag:: -Werror=⟨wflag⟩
     :noindex:
 
     :implies: ``-W<wflag>``
@@ -117,7 +117,7 @@ to abort.
     Warnings are treated only as warnings, not as errors. This is the
     default, but can be useful to negate a :ghc-flag:`-Werror` flag.
 
-.. ghc-flag:: -Wwarn=<wflag>
+.. ghc-flag:: -Wwarn=⟨wflag⟩
     :noindex:
 
     Causes a specific warning to be treated as normal warning, not fatal error.
@@ -562,7 +562,7 @@ of ``-W(no-)*``.
         h = \[] -> 2
         Just k = f y
 
-.. ghc-flag:: -fmax-pmcheck-iterations=<N>
+.. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩
 
     :default: 2000000
 
index 84dae9f..822199a 100644 (file)
@@ -309,7 +309,7 @@ The available mode flags are:
     generate dependency information suitable for use in a ``Makefile``.
     See :ref:`makefile-dependencies`.
 
-.. ghc-flag:: --frontend <module>
+.. ghc-flag:: --frontend ⟨module⟩
 
     .. index::
         single: frontend plugins; using
@@ -417,9 +417,9 @@ The main advantages to using ``ghc --make`` over traditional
 -  GHC re-calculates the dependencies each time it is invoked, so the
    dependencies never get out of sync with the source.
 
--  Using the :ghc-flag:`-j` flag, you can compile modules in parallel. Specify
-   ``-j⟨N⟩`` to compile ⟨N⟩ jobs in parallel. If N is omitted,
-   then it defaults to the number of processors.
+-  Using the :ghc-flag:`-j[⟨n⟩]` flag, you can compile modules in parallel.
+   Specify ``-j ⟨n⟩`` to compile ⟨n⟩ jobs in parallel. If ⟨n⟩ is omitted, then
+   it defaults to the number of processors.
 
 Any of the command-line options described in the rest of this chapter
 can be used with ``--make``, but note that any options you give on the
@@ -445,7 +445,7 @@ The source files for the program don't all need to be in the same
 directory; the :ghc-flag:`-i` option can be used to add directories to the
 search path (see :ref:`search-path`).
 
-.. ghc-flag:: -j [N]
+.. ghc-flag:: -j[⟨n⟩]
 
     Perform compilation in parallel when possible. GHC will use up to ⟨N⟩
     threads during compilation. If N is omitted, then it defaults to the
@@ -549,10 +549,11 @@ to compile the Haskell source file ``Foo.hs`` to an object file
 Overriding the default behaviour for a file
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-As described above, the way in which a file is processed by GHC depends
-on its suffix. This behaviour can be overridden using the :ghc-flag:`-x` option:
+As described above, the way in which a file is processed by GHC depends on its
+suffix. This behaviour can be overridden using the :ghc-flag:`-x ⟨suffix⟩`
+option:
 
-.. ghc-flag:: -x <suffix>
+.. ghc-flag:: -x ⟨suffix⟩
 
     Causes all files following this option on the command line to be
     processed as if they had the suffix ⟨suffix⟩. For example, to
@@ -791,7 +792,7 @@ messages and in GHCi:
                   in a’
         or by using the flag -fno-warn-unused-do-bind
 
-.. ghc-flag:: -fdiagnostics-color=(always|auto|never)
+.. ghc-flag:: -fdiagnostics-color=⟨always|auto|never⟩
 
     Causes GHC to display error messages with colors.  To do this, the
     terminal must have support for ANSI color codes, or else garbled text will
@@ -867,7 +868,7 @@ messages and in GHCi:
     start at zero. This choice was made to follow existing convention
     (i.e. this is how Emacs does it).
 
-.. ghc-flag:: -H <size>
+.. ghc-flag:: -H ⟨size⟩
 
     Set the minimum size of the heap to ⟨size⟩. This option is
     equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`.
index d517048..99f921c 100644 (file)
@@ -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
index e68216b..1d643a1 100644 (file)
@@ -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
index b976cdb..65f5eba 100644 (file)
@@ -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
          }
index 142e207..6bc4139 100644 (file)
@@ -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>`"
index 3142020..20d6f1f 100644 (file)
@@ -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"
index c542fa3..f1d4336 100644 (file)
@@ -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"
index 792ee9f..e0afb61 100644 (file)
@@ -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
          }
index 373773c..d2aed64 100644 (file)
@@ -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"
index 65ead95..9e13fb8 100644 (file)
@@ -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
index cbd79f1..bf903bc 100644 (file)
@@ -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
          }
index f302f56..54c886e 100644 (file)
@@ -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
          }
index 1ae7d6e..a948b94 100644 (file)
@@ -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``"
index c7b2894..8da7df3 100644 (file)
@@ -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``)"
index 62fe99a..1621311 100644 (file)
@@ -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
          }
index ff1e5a9..ba58e62 100644 (file)
@@ -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"
          }
index 620c731..da88ec6 100644 (file)
@@ -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