document the embedded grammars in Haskell & Java

1 files changed, 107 insertions, 68 deletions

diff --git a/doc/runtime-api.html b/doc/runtime-api.html
index d8759e01b..100fd4ffb 100644
--- a/doc/runtime-api.html
+++ b/doc/runtime-api.html
@@ -550,13 +550,114 @@ There are also the methods <tt>UnAbs</tt>, <tt>UnInt</tt>, <tt>UnFloat</tt> and
 </span>
 </p>
 
+Constructing new trees is also easy. You can either use 
+<tt>readExpr</tt> to read trees from strings, or you can
+construct new trees from existing pieces. This is possible by
+<span class="python">
+using the constructor for <tt>pgf.Expr</tt>:
+<pre class="python">
+>>> quant = pgf.readExpr("DetQuant IndefArt NumSg")
+>>> e2 = pgf.Expr("DetCN", [quant, e])
+>>> print(e2)
+DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N))
+</pre>
+</span>
+<span class="haskell">
+using the functions <tt>mkApp</tt>, <tt>mkStr</tt>, <tt>mkInt</tt>, <tt>mkFloat</tt> and <tt>mkMeta</tt>:
+<pre class="haskell">
+Prelude PGF2> let Just quant = readExpr "DetQuant IndefArt NumSg"
+Prelude PGF2> let e2 = mkApp "DetCN" [quant, e]
+Prelude PGF2> print e2
+DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N))
+</pre>
+</span>
+<span class="java">
+using the constructor for <tt>Expr</tt>:
+<pre class="java">
+Expr quant = Expr.readExpr("DetQuant IndefArt NumSg");
+Expr e2 = new Expr("DetCN", new Expr[] {quant, e});
+System.out.println(e2);
+</pre>
+</span>
+<span class="csharp">
+using the constructor for <tt>Expr</tt>:
+<pre class="csharp">
+Expr quant = Expr.ReadExpr("DetQuant IndefArt NumSg");
+Expr e2 = new Expr("DetCN", new Expr[] {quant, e});
+Console.WriteLine(e2);
+</pre>
+</span>
+
+<h2>Embedded GF Grammars</h2>
+
+<p>If the host application needs to do a lot of expression manipulations,
+then it is helpful to use a higher-level API to the grammar,
+also known as "embedded grammars" in GF. The advantage is that
+you can construct and analyze expressions in a more compact way.</p> 
+
+<span class="python">
+<p>In Python you first have to <tt>embed</tt> the grammar by calling:
+<pre class="python">
+>>> gr.embed("App")
+&lt;module 'App' (built-in)&gt;
+</pre>
+After that whenever you need the API you should import the module:
+<pre class="python">
+>>> import App
+</pre>
+</p>
+<p>Now creating new trees is just a matter of calling ordinary Python
+functions:
+<pre class="python">
+>>> print(App.DetCN(quant,e))
+DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN house_N))
+</pre>
+</p>
+</span>
+<span class="haskell">
+<p>In order to access the API you first need to generate
+one boilerplate Haskell module with the compiler:
+<pre class="haskell">
+$ gf -make -output-format=haskell App.pgf
+</pre>
+This module will expose all functions in the abstract syntax
+as data type constructors together with methods for conversion from
+a generic expression to Haskell data and vice versa. When you need the API you can just import the module:
+<pre class="haskell">
+Prelude PGF2> import App
+</pre>
+</p>
+<p>Now creating new trees is just a matter of writing ordinary Haskell
+code:
+<pre class="haskell">
+Prelude PGF2 App> print (gf (GDetCN (GDetQuant GIndefArt GNumSg) (GAdjCN (GPositA Gred_A) (GUseN Ghouse_N))))
+</pre>
+The only difference is that to the name of every abstract syntax function
+the compiler adds a capital 'G' in order to guarantee that there are no conflicts
+and that all names are valid names for Haskell data constructors. Here <tt>gf</tt> is a function
+which converts from the data type representation to generic GF expressions.</p>
+
+<p>The converse function <tt>fg</tt> converts an expression to a data type expression.
+This is useful for instance if you want to do pattern matching
+on the structure of the expression:
+<pre class="haskell">
+visit = case fg e2 of
+          GDetCN quant cn -> do putStrLn "Found DetCN"
+                                visit cn
+          GAdjCN adj   cn -> do putStrLn "Found AdjCN"
+                                visit cn
+          e               -> return ()
+</pre>
+</p>
+</span>
+
 <span class="python">
 <p>
-For more complex analyses you can use the visitor pattern.
-In object oriented languages this is just a clumpsy way to do
+Analysing expressions is also made easier by using the visitor pattern.
+In object oriented languages this is a clumpsy way to do
 what is called pattern matching in most functional languages.
 You need to define a class which has one method for each function
-in the abstract syntax of the grammar. If the functions is called
+in the abstract syntax that you want to handle. If the functions is called
 <tt>f</tt> then you need a method called <tt>on_f</tt>. The method
 will be called each time when the corresponding function is encountered,
 and its arguments will be the arguments from the original tree.
@@ -589,11 +690,11 @@ we call <tt>visit</tt> recursively to go deeper into the tree.
 </span>
 <span class="java">
 <p>
-For more complex analyses you can use the visitor pattern.
-In object oriented languages this is just a clumpsy way to do
+Analysing expressions is also made easier by using the visitor pattern.
+In object oriented languages this is a clumpsy way to do
 what is called pattern matching in most functional languages.
 You need to define a class which has one method for each function
-in the abstract syntax of the grammar. If the functions is called
+in the abstract syntax that you want to handle. If the functions is called
 <tt>f</tt> then you need a method called <tt>on_f</tt>. The method
 will be called each time when the corresponding function is encountered,
 and its arguments will be the arguments from the original tree.
@@ -627,68 +728,6 @@ we call <tt>visit</tt> recursively to go deeper into the tree.
 </p>
 </span>
 
-Constructing new trees is also easy. You can either use 
-<tt>readExpr</tt> to read trees from strings, or you can
-construct new trees from existing pieces. This is possible by
-<span class="python">
-using the constructor for <tt>pgf.Expr</tt>:
-<pre class="python">
->>> quant = pgf.readExpr("DetQuant IndefArt NumSg")
->>> e2 = pgf.Expr("DetCN", [quant, e])
->>> print(e2)
-DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N))
-</pre>
-</span>
-<span class="haskell">
-using the functions <tt>mkApp</tt>, <tt>mkStr</tt>, <tt>mkInt</tt>, <tt>mkFloat</tt> and <tt>mkMeta</tt>:
-<pre class="haskell">
-Prelude PGF2> let Just quant = readExpr "DetQuant IndefArt NumSg"
-Prelude PGF2> let e2 = mkApp "DetCN" [quant, e]
-Prelude PGF2> print e2
-DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N))
-</pre>
-</span>
-<span class="java">
-using the constructor for <tt>Expr</tt>:
-<pre class="java">
-Expr quant = Expr.readExpr("DetQuant IndefArt NumSg");
-Expr e2 = new Expr("DetCN", new Expr[] {quant, e});
-System.out.println(e2);
-</pre>
-</span>
-<span class="csharp">
-using the constructor for <tt>Expr</tt>:
-<pre class="csharp">
-Expr quant = Expr.ReadExpr("DetQuant IndefArt NumSg");
-Expr e2 = new Expr("DetCN", new Expr[] {quant, e});
-Console.WriteLine(e2);
-</pre>
-</span>
-
-<span class="python">
-<h2>Embedded GF Grammars</h2>
-
-The GF compiler allows for easy integration of grammars in Haskell
-applications. For that purpose the compiler generates Haskell code
-that makes the integration of grammars easier. Since Python is a
-dynamic language the same can be done at runtime. Once you load
-the grammar you can call the method <tt>embed</tt>, which will
-dynamically create a Python module with one Python function 
-for every function in the abstract syntax of the grammar.
-After that you can simply import the module:
-<pre class="python">
->>> gr.embed("App")
-&lt;module 'App' (built-in)&gt;
->>> import App
-</pre>
-Now creating new trees is just a matter of calling ordinary Python
-functions:
-<pre class="python">
->>> print(App.DetCN(quant,e))
-DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN house_N))
-</pre>
-</span>
-
 <h2>Access the Morphological Lexicon</h2>
 
 There are two methods that gives you direct access to the morphological