[commit: ghc] master: Fix and complete runghc documentation (d168c41)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/d168c41a231cd92ca993e0bdd621cf554694df1c/ghc

>---------------------------------------------------------------

commit d168c41a231cd92ca993e0bdd621cf554694df1c
Author: Harendra Kumar <harendra.kumar at gmail.com>
Date:   Tue Aug 30 16:54:30 2016 -0400

    Fix and complete runghc documentation
    
    Reviewers: austin, thomie, bgamari
    
    Reviewed By: bgamari
    
    Differential Revision: https://phabricator.haskell.org/D2463
    
    GHC Trac Issues: #12517


>---------------------------------------------------------------

d168c41a231cd92ca993e0bdd621cf554694df1c
 docs/users_guide/runghc.rst | 58 +++++++++++++++++++++++++++++++++------------
 utils/runghc/Main.hs        |  1 +
 2 files changed, 44 insertions(+), 15 deletions(-)

diff --git a/docs/users_guide/runghc.rst b/docs/users_guide/runghc.rst
index d823e35..fcc8cf8 100644
--- a/docs/users_guide/runghc.rst
+++ b/docs/users_guide/runghc.rst
@@ -11,7 +11,7 @@ compile them.
 
 .. _runghc-introduction:
 
-Flags
+Usage
 -----
 
 The ``runghc`` command-line looks like:
@@ -20,17 +20,45 @@ The ``runghc`` command-line looks like:
 
     runghc [runghc flags] [GHC flags] module [program args]
 
-The runghc flags are ``-f /path/to/ghc``, which tells runghc which GHC
-to use to run the program, and ``--help``, which prints usage
-information. If it is not given then runghc will search for GHC in the
-directories in the system search path.
-
-runghc will try to work out where the boundaries between
-``[runghc flags]`` and ``[GHC flags]``, and ``[program args]`` and
-``module`` are, but you can use a ``--`` flag if it doesn't get it
-right. For example, ``runghc -- -Wunused-bindings Foo`` means
-runghc won't try to use ``warn-unused-bindings`` as the path to GHC, but
-instead will pass the flag to GHC. If a GHC flag doesn't start with a
-dash then you need to prefix it with ``--ghc-arg=`` or runghc will think
-that it is the program to run, e.g.
-``runghc -package-db --ghc-arg=foo.conf Main.hs``.
+Any flags not recognized by runghc are automatically passed to GHC.
+If a flag is recognized by both runghc and GHC but you want to
+pass it to GHC then you can place it after a ``--`` separator. Flags after the
+separator are treated as GHC only flags. Alternatively you can use the runghc
+option ``--ghc-arg=<arg>`` to pass any flag or argument directly to GHC.
+
+``module`` could be a Haskell source filename with or without the extension.
+If for some reason the filename starts with a ``-`` you can use a second
+``--`` to indicate the end of flags. Anything following a second
+``--`` will be considered a program file or module name followed by its
+arguments. For example:
+
+- ``runghc -- -- -hello.hs``
+
+runghc flags
+------------
+
+runghc accepts the following flags:
+
+- ``-f /path/to/ghc``: tell runghc the path of GHC executable to use to run the program. By default runghc will search for GHC in the directories in the system search path.
+- ``--ghc-arg=<arg>``: Pass an option or argument to GHC
+- ``--help``: print usage information.
+- ``--version``: print version information.
+
+GHC Flags
+---------
+
+As discussed earlier, use ``--`` or ``--ghc-arg=<arg>`` to disambiguate GHC
+flags when needed. For example, ``-f`` is recognized by runghc, therefore to
+pass ``-fliberate-case`` to GHC use any of the following:
+
+- ``runghc -- -fliberate-case``
+- ``runghc --ghc-arg=-fliberate-case``
+
+Note that any non-flag arguments are never passed to GHC. An unused non-flag
+argument will be considered as the name of the program to run. If a GHC flag
+takes an argument use ``--ghc-arg=<arg>`` to pass the argument to GHC.
+For example, if you want to pass ``-package foo`` to GHC use any of the
+following:
+
+- ``runghc -package --ghc-arg=foo Main.hs``
+- ``runghc --ghc-arg=-package --ghc-arg=foo Main.hs``
diff --git a/utils/runghc/Main.hs b/utils/runghc/Main.hs
index d048125..001d902 100644
--- a/utils/runghc/Main.hs
+++ b/utils/runghc/Main.hs
@@ -107,6 +107,7 @@ printUsage = do
     putStrLn ""
     putStrLn "The runghc flags are"
     putStrLn "    -f /path/to/ghc       Tell runghc where GHC is"
+    putStrLn "    --ghc-arg=<arg>       Pass an option or argument to GHC"
     putStrLn "    --help                Print this usage information"
     putStrLn "    --version             Print version number"