[commit: ghc] wip/pattern-synonyms: Add user documentation for explicitly-bidirectional pattern synonyms (9b39096)

[git at git.haskell.org]

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

On branch  : wip/pattern-synonyms
Link       : http://ghc.haskell.org/trac/ghc/changeset/9b390965c432faf0cc9aba3a14e1be3bee37e73b/ghc

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

commit 9b390965c432faf0cc9aba3a14e1be3bee37e73b
Author: Dr. ERDI Gergo <gergo at erdi.hu>
Date:   Tue Jul 29 11:33:57 2014 +0200

    Add user documentation for explicitly-bidirectional pattern synonyms


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

9b390965c432faf0cc9aba3a14e1be3bee37e73b
 docs/users_guide/glasgow_exts.xml | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index f1d7b94..123ab53 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -987,9 +987,15 @@ Which enables us to rewrite our functions in a much cleaner style:
 In this case, <literal>Head</literal> <replaceable>x</replaceable>
 cannot be used in expressions, only patterns, since it wouldn't
 specify a value for the <replaceable>xs</replaceable> on the
-right-hand side.
+right-hand side. We can give an explicit inversion of a pattern
+synonym using the following syntax:
 </para>
 
+<programlisting>
+  pattern Head x <- x:xs where
+    Head x = [x]
+</programlisting>
+
 <para>
 The syntax and semantics of pattern synonyms are elaborated in the
 following subsections.  
@@ -1008,6 +1014,10 @@ bidirectional. The syntax for unidirectional pattern synonyms is:
   and the syntax for bidirectional pattern synonyms is:
 <programlisting>
   pattern Name args = pat
+</programlisting> or
+<programlisting>
+  pattern Name args <- pat where
+    Name args = expr
 </programlisting>
   Either prefix or infix syntax can be
   used.
@@ -1020,11 +1030,12 @@ bidirectional. The syntax for unidirectional pattern synonyms is:
 </para>
 <para>
   The variables in the left-hand side of the definition are bound by
-  the pattern on the right-hand side. For bidirectional pattern
-  synonyms, all the variables of the right-hand side must also occur
-  on the left-hand side; also, wildcard patterns and view patterns are
-  not allowed. For unidirectional pattern synonyms, there is no
-  restriction on the right-hand side pattern.
+  the pattern on the right-hand side. For implicitly bidirectional
+  pattern synonyms, all the variables of the right-hand side must also
+  occur on the left-hand side; also, wildcard patterns and view
+  patterns are not allowed. For unidirectional and
+  explicitly-bidirectional pattern synonyms, there is no restriction
+  on the right-hand side pattern.
 </para>
 
 <para>