Fix more documentation wibbles
[ghc.git] / docs / users_guide / using.rst
index 3d3ef34..dff9603 100644 (file)
@@ -93,7 +93,7 @@ to the files ``Foo.hs`` and ``Bar.hs``.
     Note that command-line options are *order-dependent*, with arguments being
     evaluated from left-to-right. This can have seemingly strange effects in the
     presence of flag implication. For instance, consider
-    :ghc-flag:`-fno-specialise` and :ghc-flag:`-O1` (which implies
+    :ghc-flag:`-fno-specialise <-fspecialise>` and :ghc-flag:`-O1` (which implies
     :ghc-flag:`-fspecialise`). These two command lines mean very different
     things:
 
@@ -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,8 +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.
+-  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
@@ -444,11 +445,12 @@ 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. Note that compilation of a module may not
-    begin until its dependencies have been built.
+    threads during compilation. If N is omitted, then it defaults to the
+    number of processors. Note that compilation of a module may not begin
+    until its dependencies have been built.
 
 .. _eval-mode:
 
@@ -547,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
@@ -615,6 +618,12 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and
     list of some in the instances it knows about. With this flag it
     prints *all* the instances it knows about.
 
+.. ghc-flag:: -fhide-source-paths
+
+    Starting with minimal verbosity (``-v1``, see :ghc-flag:`-v`), GHC
+    displays the name, the source path and the target path of each compiled
+    module. This flag can be used to reduce GHC's output by hiding source paths
+    and target paths.
 
 The following flags control the way in which GHC displays types in error
 messages and in GHCi:
@@ -631,7 +640,7 @@ messages and in GHCi:
         (>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b
 
 .. _pretty-printing-types:
-    
+
 .. ghc-flag:: -fprint-explicit-foralls
 
     Using :ghc-flag:`-fprint-explicit-foralls` makes
@@ -687,7 +696,7 @@ messages and in GHCi:
 .. ghc-flag:: -fprint-explicit-runtime-reps
 
     When :ghc-flag:`-fprint-explicit-runtime-reps` is enabled, GHC prints
-    ``RuntimeRep`` type variables for runtime-representation-polymorphic types.
+    ``RuntimeRep`` type variables for levity-polymorphic types.
     Otherwise GHC will default these to ``PtrRepLifted``. For example,
 
     .. code-block:: none
@@ -784,6 +793,52 @@ messages and in GHCi:
                   in a’
         or by using the flag -fno-warn-unused-do-bind
 
+.. 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
+    appear.  The default value is ``auto``, which means GHC will make an
+    attempt to detect whether terminal supports colors and choose accordingly.
+
+    The precise color scheme is controlled by the environment variable
+    ``GHC_COLORS`` (or ``GHC_COLOURS``).  This can be set to colon-separated
+    list of ``key=value`` pairs.  These are the default settings:
+
+    .. code-block:: none
+
+        header=:message=1:warning=1;35:error=1;31:fatal=1;31:margin=1;34
+
+    Each value is expected to be a `Select Graphic Rendition (SGR) substring
+    <https://en.wikipedia.org/wiki/ANSI_escape_code#graphics>`_.  The
+    formatting of each element can inherit from parent elements.  For example,
+    if ``header`` is left empty, it will inherit the formatting of
+    ``message``.  Alternatively if ``header`` is set to ``1`` (bold), it will
+    be bolded but still inherits the color of ``message``.
+
+    Currently, in the primary message, the following inheritance tree is in
+    place:
+
+    - ``message``
+
+      - ``header``
+
+        - ``warning``
+        - ``error``
+        - ``fatal``
+
+    In the caret diagnostics, there is currently no inheritance at all between
+    ``margin``, ``warning``, ``error``, and ``fatal``.
+
+    The environment variable can also be set to the magical values ``never``
+    or ``always``, which is equivalent to setting the corresponding
+    ``-fdiagnostics-color`` flag but with lower precedence.
+
+.. ghc-flag:: -f[no-]diagnostics-show-caret
+
+    Controls whether GHC displays a line of the original source code where the
+    error was detected.  This also affects the associated caret symbol that
+    points at the region of code at fault.  The flag is on by default.
+
 .. ghc-flag:: -ferror-spans
 
     Causes GHC to emit the full source span of the syntactic entity
@@ -816,7 +871,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`.
@@ -854,7 +909,6 @@ Some flags only make sense for particular target platforms.
     SSE2 is unconditionally used on x86-64 platforms.
 
 .. ghc-flag:: -msse4.2
-    :noindex:
 
     (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
     implement some floating point and bit operations when using the