Various documentation improvements suggested by Bulat Ziganshin

3 files changed, 52 insertions, 18 deletions

diff --git a/docs/users_guide/6.6-notes.xml b/docs/users_guide/6.6-notes.xml
index 0e7b12b949..6b6df22f30 100644
--- a/docs/users_guide/6.6-notes.xml
+++ b/docs/users_guide/6.6-notes.xml
@@ -17,14 +17,6 @@
       </listitem>
       <listitem>
         <para>
-          GHC's modules are now also bundled into a
-          <literal>ghc</literal> package, allowing programs to make use
-          of GHC as a library. The interface has not yet been properly
-          designed, so is subject to change.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
           GHC now handles impredicative polymorphism and there are
           changes to the way scoped type variables work; see
           <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-users/2006-January/009565.html"> Simon's e-mail</ulink>
@@ -297,10 +289,21 @@
       </listitem>
       <listitem>
         <para>
-          It is now possible, with the <literal>-I</literal> RTS flag,
-          to control the amount of idle time that happens before a major
-          GC is performed. There is more detail in
-          <xref linkend="rts-options-gc" />.
+          If the program is idle for a certain amount of time then GHC
+          will now take the opportunity to do a major garbage collection.
+          The amount of idle time that is required before that happens
+          is controlled by the new <literal>-I</literal> RTS flag.
+          There is more detail in <xref linkend="rts-options-gc" />.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          It is now possible to control the frequency that the RTS clock
+          ticks at with the new <literal>-V</literal> RTS flag. This is
+          normally handled automatically by other flags, but this flag
+          is needed if you want to increase the resolution of the time
+          profiler.
+          For more details see <xref linkend="rts-options-misc" />.
         </para>
       </listitem>
       <listitem>
@@ -311,8 +314,9 @@
       </listitem>
       <listitem>
         <para>
-          The <option>-split-objs</option> flag, which makes libraries
-          smaller, can now be used with <option>--make</option> and hence
+          The <option>-split-objs</option> flag, which when used to compile
+          libraries means executables using the library will be smaller,
+          can now be used with <option>--make</option> and hence
           can be used by cabal.
           See <xref linkend="options-linker" /> for more information.
         </para>
@@ -486,6 +490,7 @@
             <literal>inline</literal> which, provided the RHS is visible
             to the compiler, forcibly inlines its argument.
             Otherwise, it acts like <literal>id</literal>.
+            For more details, see <xref linkend="special-ids" />.
           </para>
         </listitem>
         <listitem>
@@ -493,6 +498,7 @@
             <literal>GHC.Exts</literal> now provides a function
             <literal>lazy</literal> which forces GHC to think that its
             argument is lazy in its first argument.
+            For more details, see <xref linkend="special-ids" />.
           </para>
         </listitem>
         <listitem>
@@ -1613,6 +1619,24 @@
   </sect2>
 
   <sect2>
+    <title>GHC As A Library</title>
+      <para>
+        Version number 6.6.
+      </para>
+      <para>
+        The internal modules of GHC are now available as a library, package
+        name <literal>ghc</literal>.
+        The interface has not been designed with use by other programs
+        in mind, so expect the API to vary radically in future
+        releases.
+      </para>
+      <para>
+        An introduction to using the library can be found
+        <ulink url="http://haskell.org/haskellwiki/GHC/As_a_library">on the wiki</ulink>.
+      </para>
+  </sect2>
+
+  <sect2>
     <title>Internal changes</title>
     <itemizedlist>
       <listitem>
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index f8ea3c7264..09fd3f509f 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -3778,9 +3778,9 @@ pattern binding must have the same context.  For example, this is fine:
 <!-- ====================== Generalised algebraic data types =======================  -->
 
 <sect1 id="gadt">
-<title>Generalised Algebraic Data Types</title>
+<title>Generalised Algebraic Data Types (GADTs)</title>
 
-<para>Generalised Algebraic Data Types (GADTs) generalise ordinary algebraic data types by allowing you
+<para>Generalised Algebraic Data Types generalise ordinary algebraic data types by allowing you
 to give the type signatures of constructors explicitly.  For example:
 <programlisting>
   data Term a where
@@ -3801,7 +3801,12 @@ for these <literal>Terms</literal>:
   eval (If b e1 e2) = if eval b then eval e1 else eval e2
   eval (Pair e1 e2) = (eval e1, eval e2)
 </programlisting>
-These and many other examples are given in papers by Hongwei Xi, and Tim Sheard.
+These and many other examples are given in papers by Hongwei Xi, and
+Tim Sheard. There is a longer introduction
+<ulink url="http://haskell.org/haskellwiki/GADT">on the wiki</ulink>,
+and Ralf Hinze's
+<ulink url="http://www.informatik.uni-bonn.de/~ralf/publications/With.pdf">Fun with phantom types</ulink> also has a number of examples. Note that papers
+may use different notation to that implemented in GHC.
 </para>
 <para>
 The rest of this section outlines the extensions to GHC that support GADTs. 
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index 35e74c3544..cc9fbfbf16 100644
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -725,7 +725,12 @@ $ cat foo.hspp</screen>
           <para>Tell the linker to split the single object file that
           would normally be generated into multiple object files,
           one per top-level Haskell function or type in the module.
-          We use this feature for building GHC's libraries libraries
+          This only makes sense for libraries, where it means that
+          executables linked against the library are smaller as they only
+          link against the object files that they need. However, assembling
+          all the sections separately is expensive, so this is slower than
+          compiling normally.
+          We use this feature for building GHC's libraries
           (warning: don't use it unless you know what you're
           doing!).</para>
         </listitem>