Be more specific about file-header pragmas

Document the rules for pragmas that must occur at the top of a file.

Please merge this patch

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 345d694..e787626 100644 (file)
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -789,7 +789,7 @@
            </row>
            <row>
              <entry><option>-XKindSignatures</option></entry>
-             <entry>Enable kind signatures.</entry>
+             <entry>Enable <link linkend="kinding">kind signatures</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoKindSignatures</option></entry>
            </row>

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index da6a125..797a509 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -3604,7 +3604,10 @@ kind for the type variable <literal>cxt</literal>.
 </para>
 <para>
 GHC now instead allows you to specify the kind of a type variable directly, wherever
-a type variable is explicitly bound.  Namely:
+a type variable is explicitly bound, with the flag <option>-XKindSignatures</option>.
+</para>
+<para>
+This flag enables kind signatures in the following places:
 <itemizedlist>
 <listitem><para><literal>data</literal> declarations:
 <screen>
@@ -5306,6 +5309,87 @@ Assertion failures can be caught, see the documentation for the
     unrecognised <replaceable>word</replaceable> is (silently)
     ignored.</para>
 
+    <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>.  A file-header
+      pragma must precede the <literal>module</literal> keyword in the file.  
+      There can be as many file-header pragmas as you please, and they can be
+      preceded or followed by comments.</para>
+
+    <sect2 id="language-pragma">
+      <title>LANGUAGE pragma</title>
+
+      <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
+      <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
+
+      <para>The <literal>LANGUAGE</literal> pragma allows language extensions to be enabled 
+       in a portable way.
+       It is the intention that all Haskell compilers support the
+       <literal>LANGUAGE</literal> pragma with the same syntax, although not
+       all extensions are supported by all compilers, of
+       course.  The <literal>LANGUAGE</literal> pragma should be used instead
+       of <literal>OPTIONS_GHC</literal>, if possible.</para>
+
+      <para>For example, to enable the FFI and preprocessing with CPP:</para>
+
+<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
+
+        <para><literal>LANGUAGE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+      <para>Every language extension can also be turned into a command-line flag
+       by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>.
+       (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.
+      </para>
+
+      <para>A list of all supported language extensions can be obtained by invoking
+       <literal>ghc --supported-languages</literal> (see <xref linkend="modes"/>).</para>
+
+      <para>Any extension from the <literal>Extension</literal> type defined in
+       <ulink
+         url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink>
+       may be used.  GHC will report an error if any of the requested extensions are not supported.</para>
+    </sect2>
+
+
+    <sect2 id="options-pragma">
+      <title>OPTIONS_GHC pragma</title>
+      <indexterm><primary>OPTIONS_GHC</primary>
+      </indexterm>
+      <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
+      </indexterm>
+
+      <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
+      additional options that are given to the compiler when compiling
+      this source file.  See <xref linkend="source-file-options"/> for
+      details.</para>
+
+      <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
+       than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
+    </sect2>
+
+        <para><literal>OPTIONS_GHC</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+    <sect2 id="include-pragma">
+      <title>INCLUDE pragma</title>
+
+      <para>The <literal>INCLUDE</literal> pragma is for specifying the names
+       of C header files that should be <literal>#include</literal>'d into
+       the C source code generated by the compiler for the current module (if
+       compiling via C).  For example:</para>
+
+<programlisting>
+{-# INCLUDE "foo.h" #-}
+{-# INCLUDE &lt;stdio.h&gt; #-}</programlisting>
+
+        <para><literal>INCLUDE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+      <para>An <literal>INCLUDE</literal> pragma is  the preferred alternative
+       to the <option>-#include</option> option (<xref
+         linkend="options-C-compiler" />), because the
+       <literal>INCLUDE</literal> pragma is understood by other
+       compilers.  Yet another alternative is to add the include file to each
+       <literal>foreign import</literal> declaration in your code, but we
+       don't recommend using this approach with GHC.</para>
+    </sect2>
+
     <sect2 id="deprecated-pragma">
       <title>DEPRECATED pragma</title>
       <indexterm><primary>DEPRECATED</primary>
@@ -5358,31 +5442,6 @@ Assertion failures can be caught, see the documentation for the
       <option>-fno-warn-deprecations</option>.</para>
     </sect2>
 
-    <sect2 id="include-pragma">
-      <title>INCLUDE pragma</title>
-
-      <para>The <literal>INCLUDE</literal> pragma is for specifying the names
-       of C header files that should be <literal>#include</literal>'d into
-       the C source code generated by the compiler for the current module (if
-       compiling via C).  For example:</para>
-
-<programlisting>
-{-# INCLUDE "foo.h" #-}
-{-# INCLUDE &lt;stdio.h&gt; #-}</programlisting>
-
-      <para>The <literal>INCLUDE</literal> pragma(s) must appear at the top of
-       your source file with any <literal>OPTIONS_GHC</literal>
-       pragma(s).</para>
-
-      <para>An <literal>INCLUDE</literal> pragma is  the preferred alternative
-       to the <option>-#include</option> option (<xref
-         linkend="options-C-compiler" />), because the
-       <literal>INCLUDE</literal> pragma is understood by other
-       compilers.  Yet another alternative is to add the include file to each
-       <literal>foreign import</literal> declaration in your code, but we
-       don't recommend using this approach with GHC.</para>
-    </sect2>
-
     <sect2 id="inline-noinline-pragma">
       <title>INLINE and NOINLINE pragmas</title>
 
@@ -5529,29 +5588,6 @@ happen.
       </sect3>
     </sect2>
 
-    <sect2 id="language-pragma">
-      <title>LANGUAGE pragma</title>
-
-      <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
-      <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
-
-      <para>This allows language extensions to be enabled in a portable way.
-       It is the intention that all Haskell compilers support the
-       <literal>LANGUAGE</literal> pragma with the same syntax, although not
-       all extensions are supported by all compilers, of
-       course.  The <literal>LANGUAGE</literal> pragma should be used instead
-       of <literal>OPTIONS_GHC</literal>, if possible.</para>
-
-      <para>For example, to enable the FFI and preprocessing with CPP:</para>
-
-<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
-
-      <para>Any extension from the <literal>Extension</literal> type defined in
-       <ulink
-         url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink> may be used.  GHC will report an error if any of the requested extensions are not supported.</para>
-    </sect2>
-
-
     <sect2 id="line-pragma">
       <title>LINE pragma</title>
 
@@ -5571,22 +5607,6 @@ happen.
       pragma.</para>
     </sect2>
 
-    <sect2 id="options-pragma">
-      <title>OPTIONS_GHC pragma</title>
-      <indexterm><primary>OPTIONS_GHC</primary>
-      </indexterm>
-      <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
-      </indexterm>
-
-      <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
-      additional options that are given to the compiler when compiling
-      this source file.  See <xref linkend="source-file-options"/> for
-      details.</para>
-
-      <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
-       than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
-    </sect2>
-
     <sect2 id="rules">
       <title>RULES pragma</title>