[commit: ghc] ghc-8.2: A few documentation fixes (d4d8936)

[git at git.haskell.org]

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

On branch  : ghc-8.2
Link       : http://ghc.haskell.org/trac/ghc/changeset/d4d8936d64fbd5e2104560b02cf7b2972e391945/ghc

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

commit d4d8936d64fbd5e2104560b02cf7b2972e391945
Author: David Feuer <david.feuer at gmail.com>
Date:   Sat May 20 12:56:20 2017 -0400

    A few documentation fixes
    
    `MIN_VERSION_pkg` was documented backwards. An important caveat
    about initializing the Haskell runtime was buried in a footnote.
    The documentation of `-dynamic` was (even more) confusing.
    
    Reviewers: austin, bgamari
    
    Reviewed By: bgamari
    
    Subscribers: rwbarton, thomie
    
    Differential Revision: https://phabricator.haskell.org/D3582
    
    (cherry picked from commit 5b8f95d7fca302a9ad27533b74b1a1c2364605dc)


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

d4d8936d64fbd5e2104560b02cf7b2972e391945
 docs/users_guide/bugs.rst     |  2 +-
 docs/users_guide/ffi-chap.rst | 11 ++++-------
 docs/users_guide/phases.rst   |  8 ++++++--
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index 707f66b..7ccb215 100644
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -342,7 +342,7 @@ The Foreign Function Interface
 ``hs_init()``, ``hs_exit()``
     The FFI spec requires the implementation to support re-initialising
     itself after being shut down with ``hs_exit()``, but GHC does not
-    currently support that.
+    currently support that. See :ghc-ticket:`13693`.
 
     .. index::
         single: hs_init
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
index d4bf343..35557b8 100644
--- a/docs/users_guide/ffi-chap.rst
+++ b/docs/users_guide/ffi-chap.rst
@@ -311,8 +311,10 @@ can separate out any arguments for the RTS (i.e. those arguments between
 After we've finished invoking our Haskell functions, we can call
 ``hs_exit()``, which terminates the RTS.
 
-There can be multiple calls to ``hs_init()``, but each one should be
-matched by one (and only one) call to ``hs_exit()`` [1]_.
+There can be multiple calls to ``hs_init()``, but each one should be matched by
+one (and only one) call to ``hs_exit()``. The outermost ``hs_exit()`` will
+actually de-initialise the system.  Note that currently GHC's runtime cannot
+reliably re-initialise after this has happened; see :ref:`infelicities-ffi`.
 
 .. note::
     When linking the final program, it is normally easiest to do the
@@ -320,11 +322,6 @@ matched by one (and only one) call to ``hs_exit()`` [1]_.
     don't forget the flag :ghc-flag:`-no-hs-main`, otherwise GHC
     will try to link to the ``Main`` Haskell module.
 
-.. [1]
-   The outermost ``hs_exit()`` will actually de-initialise the system.
-   Note that currently GHC's runtime cannot reliably re-initialise after
-   this has happened, see :ref:`infelicities-ffi`.
-
 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`
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 6bc9767..1efe6a4 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -324,7 +324,7 @@ defined by your local GHC installation, the following trick is useful:
     This macro is available starting GHC 8.0.  It is defined for every
     exposed package. This macro is provided for convenience to write CPP
     conditionals testing if a package version is ``x.y.z`` or
-    less.  It is identical in behavior to the ``MIN_VERSION_pkgname``
+    later.  It is identical in behavior to the ``MIN_VERSION_pkgname``
     macros that Cabal defines.
 
 .. _cpp-string-gaps:
@@ -459,7 +459,11 @@ Options affecting code generation
     :noindex:
 
     When generating code, assume that entities imported from a different
-    package will reside in a different shared library or binary.
+    package will be dynamically linked. This can reduce code size
+    tremendously, but may slow-down cross-package calls of non-inlined
+    functions. There can be some complications combining :ghc-flag:`-shared`
+    with this flag relating to linking in the RTS under Linux. See
+    :ghc-ticket:`10352`.
 
     Note that using this option when linking causes GHC to link against
     shared libraries.