From: simonpj@microsoft.com Date: Wed, 11 Feb 2009 09:39:39 +0000 (+0000) Subject: Improve documentation for LANGUAGE pragma (esp wrt cpp) X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=26c5507eccc275dde3633adb858d0b610cc127ab Improve documentation for LANGUAGE pragma (esp wrt cpp) --- diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index 05794df..8356a28 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -607,7 +607,9 @@ Language options - + Language options can be enabled either by a command-line option + , or by a {-# LANGUAGE blah #-} + pragma in the file itself. See @@ -932,7 +934,7 @@ - Enable type synonyms. + Enable type synonyms in instance heads. dynamic diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index a431dd6..fb9824c 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -38,19 +38,20 @@ documentation describes all the libraries that come with GHC. extensionsoptions controlling - The language option flag control what variation of the language are + The language option flags control what variation of the language are permitted. Leaving out all of them gives you standard Haskell 98. - Generally speaking, all the language options are introduced by "", - e.g. . - - - All the language options can be turned off by using the prefix ""; - e.g. "". - - Language options recognised by Cabal can also be enabled using the LANGUAGE pragma, - thus {-# LANGUAGE TemplateHaskell #-} (see >). + Language options can be controlled in two ways: + + Every language option can switched on by a command-line flag "" + (e.g. ), and switched off by the flag ""; + (e.g. ). + + Language options recognised by Cabal can also be enabled using the LANGUAGE pragma, + thus {-# LANGUAGE TemplateHaskell #-} (see ). + + The flag @@ -6862,10 +6863,27 @@ Assertion failures can be caught, see the documentation for the ignored. The layout rule applies in pragmas, so the closing #-} should start in a column to the right of the opening {-#. - Certain pragmas are file-header pragmas. A file-header - pragma must precede the module keyword in the file. + Certain pragmas are file-header pragmas: + + + A file-header + pragma must precede the module keyword in the file. + + There can be as many file-header pragmas as you please, and they can be - preceded or followed by comments. + preceded or followed by comments. + + + File-header pragmas are read once only, before + pre-processing the file (e.g. with cpp). + + + The file-header pragmas are: {-# LANGUAGE #-}, + {-# OPTIONS_GHC #-}, and + {-# INCLUDE #-}. + + + LANGUAGE pragma diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 439fb58..d6eb6ed 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -46,26 +46,25 @@ ghc [argument...] 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. Rather than maintaining + tight. For instance, if a Haskell source file deliberately + uses name shadowing, it should be compiled with the + option. Rather than maintaining the list of per-file options in a Makefile, it is possible to do this directly in the source file using the OPTIONS_GHC pragma OPTIONS_GHC pragma: -{-# OPTIONS_GHC -fglasgow-exts #-} +{-# OPTIONS_GHC -fno-warn-name-shadowing #-} module X where ... - OPTIONS_GHC pragmas are only looked for at - the top of your source files, upto the first - (non-literate,non-empty) line not containing - OPTIONS_GHC. Multiple OPTIONS_GHC - pragmas are recognised. Do not put comments before, or on the same line - as, the OPTIONS_GHC pragma. + OPTIONS_GHC is a file-header pragma + (see ). + + Only dynamic flags can be used in an OPTIONS_GHC pragma + (see ). Note that your command shell does not get to the source file options, they are just included literally