[commit: ghc] master: Document -XTypeOperators, which had escaped documentation altogether thus far (316e8cb)

[Simon Peyton Jones]

Repository : http://darcs.haskell.org/ghc.git/

On branch  : master

https://github.com/ghc/ghc/commit/316e8cba29ac25dccb054e9b73e2d174b7b4b61a

>---------------------------------------------------------------

commit 316e8cba29ac25dccb054e9b73e2d174b7b4b61a
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Tue Jun 25 09:59:42 2013 +0100

    Document -XTypeOperators, which had escaped documentation altogether thus far

>---------------------------------------------------------------

 docs/users_guide/flags.xml        |  2 +-
 docs/users_guide/glasgow_exts.xml | 58 ++++++++++++++++++++++++++++++++++++---
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 6b8b17c..a7b9839 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1015,7 +1015,7 @@
           </row>
           <row>
             <entry><option>-XTypeOperators</option></entry>
-            <entry>Enable type operators.</entry>
+            <entry>Enable <link linkend="type-operators">type operators</link>.</entry>
             <entry>dynamic</entry>
             <entry><option>-XNoTypeOperators</option></entry>
           </row>
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index b398597..0c4c890 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -2284,10 +2284,10 @@ to be written infix, very much like expressions.  More specifically:
   </para></listitem>
 <listitem><para>
   Types, and class constraints, can be written infix.  For example
-  <screen>
-	x :: Int :*: Bool
-        f :: (a :=: b) => a -> b
-  </screen>
+<screen>
+  x :: Int :*: Bool
+  f :: (a :=: b) => a -> b
+</screen>
   </para></listitem>
 <listitem><para>
   Back-quotes work
@@ -2313,6 +2313,56 @@ to be written infix, very much like expressions.  More specifically:
 </para>
 </sect2>
 
+<sect2 id="type-operators">
+<title>Type operators</title>
+<para>
+In types, an operator symbol like <literal>(+)</literal> is normally treated as a type
+<emphasis>variable</emphasis>, just like <literal>a</literal>.  Thus in Haskell 98 you can say
+<programlisting>
+type T (+) = ((+), (+))
+-- Just like: type T a = (a,a)
+
+f :: T Int -> Int
+f (x,y)= x
+</programlisting>
+As you can see, using operators in this way is not very useful, and Haskell 98 does not even
+allow you to write them infix.
+</para>
+<para>
+The language <option>-XTypeOperators</option> changes this behaviour:
+<itemizedlist>
+<listitem><para>
+Operator symbols become type <emphasis>constructors</emphasis> rather than 
+type <emphasis>variables</emphasis>.
+</para></listitem>
+<listitem><para>
+Operator symbols in types can be written infix, both in definitions and uses. 
+for example:
+<programlisting>
+data a + b = Plus a b
+type Foo = Int + Bool
+</programlisting>
+</para></listitem>
+<listitem><para>
+There is now some potential ambiguity in import and export lists; for example
+if you write <literal>import M( (+) )</literal> do you mean the 
+<emphasis>function</emphasis> <literal>(+)</literal> or the 
+<emphasis>type constructor</emphasis> <literal>(+)</literal>?
+The default is the former, but GHC allows you to specify the latter
+by preceding it with the keyword <literal>type</literal>, thus:
+<programlisting>
+import M( type (+) )
+</programlisting>
+</para></listitem>
+<listitem><para>
+The fixity of a type operator may be set using the usual fixity declarations
+but, as in <xref linkend="infix-tycons"/>, the function and type constructor share
+a single fixity.
+</para></listitem>
+</itemizedlist>
+</para>
+</sect2>
+
 <sect2 id="type-synonyms">
 <title>Liberalised type synonyms</title>