[commit: ghc] master: Added paragraph to user's guide about Nominal role for Set (82bbc38)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/82bbc3864ff608879cffbe0d2a4a2f8cb4ef4604/ghc

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

commit 82bbc3864ff608879cffbe0d2a4a2f8cb4ef4604
Author: Richard Eisenberg <eir at cis.upenn.edu>
Date:   Tue Aug 20 22:41:04 2013 -0400

    Added paragraph to user's guide about Nominal role for Set


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

82bbc3864ff608879cffbe0d2a4a2f8cb4ef4604
 docs/users_guide/glasgow_exts.xml |   14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 8111a81..0b16156 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -10886,6 +10886,20 @@ the user-supplied roles to make sure they don't break any promises. It would
 be bad, for example, if the user could make <literal>BadIdea</literal>'s role be R.
 </para>
 
+<para>As another example, we can consider a type <literal>Set a</literal> that
+represents a set of data, ordered according to <literal>a</literal>'s
+<literal>Ord</literal> instance. While it would generally be type-safe to
+consider <literal>a</literal> to be at role R, it is possible that a
+<literal>newtype</literal> and its base type have
+<emphasis>different</emphasis> orderings encoded in their respective
+<literal>Ord</literal> instances. This would lead to misbehavior at runtime.
+So, the author of the <literal>Set</literal> datatype would like its parameter
+to be at role N. This would be done with a declaration</para>
+
+<programlisting>
+  data Set a at N = ...
+</programlisting>
+
 <para>The other place where role annotations may be necessary are in
 <literal>hs-boot</literal> files (<xref linkend="mutual-recursion"/>), where
 the right-hand sides of definitions can be omitted. As usual, the