Commit 26c5507e authored by simonpj@microsoft.com's avatar simonpj@microsoft.com
Browse files

Improve documentation for LANGUAGE pragma (esp wrt cpp)

parent f75d258c
......@@ -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>
......
......@@ -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>
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment