<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">
</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>
<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>
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>
<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