[commit: ghc] master: Tweak holes documentation (2f6d36f)

[git at git.haskell.org]

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

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

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

commit 2f6d36f64730f044bb038e2d3da2b97ee571d763
Author: Krzysztof Gogolewski <krz.gogolewski at gmail.com>
Date:   Tue Feb 4 23:42:00 2014 +0100

    Tweak holes documentation
    
    type holes -> typed holes, reorder, minor changes


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

2f6d36f64730f044bb038e2d3da2b97ee571d763
 docs/users_guide/glasgow_exts.xml |   28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 60f8acf..a3913cc 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -7978,17 +7978,7 @@ with <option>-XNoMonoLocalBinds</option> but type inference becomes less predica
 <option>-fwarn-typed-holes</option>, which is enabled by default.</para>
 
 <para>
-The goal of the typed holes warning is not to change the type system, but to help with writing Haskell
-code. Type holes can be used to obtain extra information from the type checker, which might otherwise be hard
-to get.
-Normally, the type checker is used to decide if a module is well typed or not. Using GHCi,
-users can inspect the (inferred) type signatures of all top-level bindings. However, determining the
-type of a single term is still hard. Yet while writing code, it could be helpful to know the type of
-the term you're about to write.
-</para>
-
-<para>
-This extension allows special placeholders, written with a leading underscore (e.g. "<literal>_</literal>",
+This option allows special placeholders, written with a leading underscore (e.g. "<literal>_</literal>",
 "<literal>_foo</literal>", "<literal>_bar</literal>"), to be used as an expression.
 During compilation these holes will generate an error message describing what type is expected there,
 information about the origin of any free type variables, and a list of local bindings
@@ -7996,6 +7986,15 @@ that might help fill the hole with actual code.
 </para>
 
 <para>
+The goal of the typed holes warning is not to change the type system, but to help with writing Haskell
+code. Typed holes can be used to obtain extra information from the type checker, which might otherwise be hard
+to get.
+Normally, using GHCi, users can inspect the (inferred) type signatures of all top-level bindings.
+However, this method is less convenient with terms which are not defined on top-level or
+inside complex expressions. Holes allow to check the type of the term you're about to write.
+</para>
+
+<para>
 Holes work together well with <link linkend="defer-type-errors">deferring type errors to runtime</link>:
 with <literal>-fdefer-type-errors</literal>, the error from a hole is also deferred, effctively making the hole
 typecheck just like <literal>undefined</literal>, but with the added benefit that it will show its warning message
@@ -8023,15 +8022,15 @@ hole.hs:2:7:
 </para>
 
 <para>
-Multiple type holes can be used to find common type variables between expressions. For example:
+Multiple typed holes can be used to find common type variables between expressions. For example:
 <programlisting>
 sum :: [Int] -> Int
-sum xx = foldr _f _z xs
+sum xs = foldr _f _z xs
 </programlisting>
 Shows:
 <programlisting>
 holes.hs:2:15:
-    Found hole `_f' with type: Int-> Int -> Int
+    Found hole `_f' with type: Int -> Int -> Int
     In the first argument of `foldr', namely `_'
     In the expression: foldr _a _b _c
     In an equation for `sum': sum x = foldr _a _b _c
@@ -8070,7 +8069,6 @@ unbound.hs:1:13:
     In the second argument of `(:)', namely `_x'
     In the expression: _x : _x
     In an equation for `cons': cons = _x : _x
-Failed, modules loaded: none.
 </programlisting>
 This ensures that an unbound identifier is never reported with a too polymorphic type, like
 <literal>forall a. a</literal>, when used multiple times for types that can not be unified.