Improve documentation for LANGUAGE pragma (esp wrt cpp)

docs/users_guide/flags.xml

@@ -607,7 +607,9 @@
     <sect2>
       <title>Language options</title>
 
-      <para><xref linkend="options-language"/></para>
+      <para>Language options can be enabled either by a command-line option 
+      <option>-Xblah</option>, or by a <literal>{-# LANGUAGE blah #-}</literal>
+      pragma in the file itself.  See <xref linkend="options-language"/></para>
 
       <informaltable>
 	<tgroup cols="4" align="left" colsep="1" rowsep="1">
@@ -932,7 +934,7 @@
 	    </row>
 	    <row>
 	      <entry><option>-XTypeSynonymInstances</option></entry>
-	      <entry>Enable <link linkend="type-synonym-instances">type synonyms</link>.</entry>
+	      <entry>Enable <link linkend="flexible-instance-head">type synonyms in instance heads</link>.</entry>
 	      <entry>dynamic</entry>
 	      <entry><option>-XNoTypeSynonymInstances</option></entry>
 	    </row>

docs/users_guide/glasgow_exts.xml

@@ -38,19 +38,20 @@ documentation</ulink> describes all the libraries that come with GHC.
     <indexterm><primary>extensions</primary><secondary>options controlling</secondary>
     </indexterm>
 
-    <para>The language option flag control what variation of the language are
+    <para>The language option flags control what variation of the language are
     permitted.  Leaving out all of them gives you standard Haskell
     98.</para>
 
-    <para>Generally speaking, all the language options are introduced by "<option>-X</option>", 
-    e.g. <option>-XTemplateHaskell</option>.
-    </para>
-
-   <para> All the language options can be turned off by using the prefix "<option>No</option>"; 
-      e.g. "<option>-XNoTemplateHaskell</option>".</para>
-
-   <para> Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma,
-   thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>>). </para>
+    <para>Language options can be controlled in two ways:
+    <itemizedlist>
+      <listitem><para>Every language option can switched on by a command-line flag "<option>-X...</option>" 
+        (e.g. <option>-XTemplateHaskell</option>), and switched off by the flag "<option>-XNo...</option>"; 
+        (e.g. <option>-XNoTemplateHaskell</option>).</para></listitem>
+      <listitem><para>
+          Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma,
+          thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>). </para>
+          </listitem>
+      </itemizedlist></para>
 
     <para>The flag <option>-fglasgow-exts</option>
           <indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>
@@ -6862,10 +6863,27 @@ Assertion failures can be caught, see the documentation for the
     ignored. The layout rule applies in pragmas, so the closing <literal>#-}</literal>
     should start in a column to the right of the opening <literal>{-#</literal>. </para> 
 
-    <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>.  A file-header
-      pragma must precede the <literal>module</literal> keyword in the file.  
+    <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>:
+      <itemizedlist>
+      <listitem><para>
+	  A file-header
+	  pragma must precede the <literal>module</literal> keyword in the file.
+	  </para></listitem>
+      <listitem><para>
       There can be as many file-header pragmas as you please, and they can be
-      preceded or followed by comments.</para>
+      preceded or followed by comments.  
+	  </para></listitem>
+      <listitem><para>
+      File-header pragmas are read once only, before
+      pre-processing the file (e.g. with cpp).
+	  </para></listitem>
+      <listitem><para>
+         The file-header pragmas are: <literal>{-# LANGUAGE #-}</literal>,
+	<literal>{-# OPTIONS_GHC #-}</literal>, and
+	<literal>{-# INCLUDE #-}</literal>.
+	  </para></listitem>
+      </itemizedlist>
+      </para>
 
     <sect2 id="language-pragma">
       <title>LANGUAGE pragma</title>

docs/users_guide/using.xml

@@ -46,26 +46,25 @@ ghc [argument...]
 
       <para>Sometimes it is useful to make the connection between a
       source file and the command-line options it requires quite
-      tight. For instance, if a Haskell source file uses GHC
-      extensions, it will always need to be compiled with the
-      <option>-fglasgow-exts</option> option.  Rather than maintaining
+      tight. For instance, if a Haskell source file deliberately
+	uses name shadowing, it should be compiled with  the
+      <option>-fno-warn-name-shadowing</option> option.  Rather than maintaining
       the list of per-file options in a <filename>Makefile</filename>,
       it is possible to do this directly in the source file using the
       <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
       pragma</primary></indexterm>:</para>
 
 <programlisting>
-{-# OPTIONS_GHC -fglasgow-exts #-}
+{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
 module X where
 ...
 </programlisting>
       
-      <para><literal>OPTIONS_GHC</literal> pragmas are only looked for at
-      the top of your source files, upto the first
-      (non-literate,non-empty) line not containing
-      <literal>OPTIONS_GHC</literal>. Multiple <literal>OPTIONS_GHC</literal>
-      pragmas are recognised.  Do not put comments before, or on the same line
-	as, the <literal>OPTIONS_GHC</literal> pragma.</para>
+      <para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis>
+      (see <xref linkend="pragmas"/>).</para>
+
+      <para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma
+      (see <xref linkend="static-dynamic-flags"/>).</para>
 
       <para>Note that your command shell does not
       get to the source file options, they are just included literally