document the four new language features in the reference manual

author: kr.angelov <kr.angelov@gmail.com> 2013-11-12 16:05:02 +0000
committer: kr.angelov <kr.angelov@gmail.com> 2013-11-12 16:05:02 +0000
commit: 0090b85002e4f609be7be107d9ac251cfd436afc (patch)
tree: 42ceab8b330c6499f5297084857d577fb3d88c42 /doc
parent: 709b2bb067b4c3c2316e608e35bc59172f1452d9 (diff)
1 files changed, 105 insertions, 11 deletions
diff --git a/doc/gf-refman.html b/doc/gf-refman.html
index 188a063a8..376689a9a 100644
--- a/doc/gf-refman.html
+++ b/doc/gf-refman.html
@@ -5,7 +5,7 @@
 </HEAD><BODY BGCOLOR="white" TEXT="black">
 <P ALIGN="center"><CENTER><H1>GF Language Reference Manual</H1>
 <FONT SIZE="4">
-<I>Aarne Ranta</I><BR>February 2008
+<I>Aarne Ranta</I>, <I>Krasimir Angelov</I><BR>November 2013
 </FONT></CENTER>
 
 <P></P>
@@ -39,6 +39,7 @@
       <LI><A HREF="#toc22">Linearization type definitions, lincat</A>
       <LI><A HREF="#toc23">Linearization definitions, lin</A>
       <LI><A HREF="#toc24">Linearization default definitions, lindef</A>
+      <LI><A HREF="#toc24_r">Linearization reference definitions, linref</A>
       <LI><A HREF="#toc25">Printname definitions, printname cat and printname fun</A>
       <LI><A HREF="#toc26">Parameter type definitions, param</A>
       <LI><A HREF="#toc27">Parameter values</A>
@@ -968,8 +969,15 @@ name to the scope.
 <TD>yes</TD>
 </TR>
 <TR>
-<TD><CODE>lindef</CODE> f = t</TD>
-<TD>f fun, t term</TD>
+<TD><CODE>lindef</CODE> C = t</TD>
+<TD>C cat, t term</TD>
+<TD>concrete*</TD>
+<TD>yes</TD>
+<TD>no</TD>
+</TR>
+<TR>
+<TD><CODE>linref</CODE> C = t</TD>
+<TD>C cat, t term</TD>
 <TD>concrete*</TD>
 <TD>yes</TD>
 <TD>no</TD>
@@ -1355,11 +1363,17 @@ type of <I>C</I>.
 Linearization defaults are invoked when linearizing variable bindings
 in higher-order abstract syntax. A variable symbol is then presented
 as a string, which must be converted to correct type in order for
-linearization not to fail with an error. 
+the linearization not to fail with an error. 
 </P>
 <P>
-The defaults can also be used for linearizing metavariables
-in an interactive syntax editor.
+The other use of the defaults is for linearizing metavariables
+and abstract functions without linearization in the concrete syntax.
+In the first case the default linearization is applied to 
+the string <CODE>"?X"</CODE> where <CODE>X</CODE> is the unique index 
+of the metavariable, and in the second case the string is 
+<CODE>"[f]"</CODE> where <CODE>f</CODE> is the name of the abstract 
+function with missing linearization.
+
 </P>
 <P>
 Usually, linearization defaults are generated by using the default
@@ -1376,8 +1390,62 @@ definition is by structural recursion on the type:
 
 <P>
 The notion of the first value of a parameter type (#1(P)) is defined
-<a href="#paramvalues">here</a> below.
+<a href="#paramvalues">below</a>.
 </P>
+<A NAME="toc24_r"></A>
+<H3>Linearization reference definitions, linref</H3>
+<P>
+<a name="linrefjudgements"></a>
+</P>
+<P>
+A linearization reference definition,
+<center>
+  <CODE>linref</CODE> <I>C</I> <CODE>=</CODE> <I>t</I>
+</center>
+defines the reference linearization of category <I>C</I>, i.e. the function
+applicable to an object of the linearization type of <I>C</I> to make it into a string.
+</P>
+<P>
+The reference linearization is always applied to the top-level node
+of the abstract syntax tree. For example when we linearize the
+tree <CODE>f x1 x2 .. xn</CODE>, then we first apply <CODE>f</CODE>
+to its arguments which gives us an object of the linearization type of
+its category. After that we apply the reference linearization
+for the same category to get a string out of the object. This
+is particularly useful when the linearization type of <I>C</I>
+contains discontious constituents. In this case usually the reference
+linearization glues the constituents together to produce an
+intuitive linearization string.
+</P>
+<P>
+The reference linearization is also used for linearizing metavariables
+which stand in function position. For example the tree
+<CODE>f (? x1 x2 .. xn)</CODE> is linearized as follows. Each
+of the arguments <CODE>x1 x2 .. xn</CODE> is linearized, and after that
+the reference linearization of the its category is applied 
+to the output of the linearization. The result is a sequence of <CODE>n</CODE>
+strings which are concatenated into a single string. The final string
+is the input to the default linearization of the category 
+for the argument of <CODE>f</CODE>. After applying the default linearization
+we get an object that we could safely pass to <CODE>f</CODE>.
+</P>
+<P>
+Usually, linearization references are generated by using the
+rule that "picks the first string in the linearization type". The precise
+definition is by structural recursion on the type:
+</P>
+<UL>
+<LI>reference(Str,o) = Just o
+<LI>reference(P,s) = Nothing
+<LI>reference(P =&gt; T,o) = reference(T,o ! #1(P)) || reference(T,o ! #2(P)) || ... || reference(T,o ! #n(P))
+<LI>reference({r1 : R1; ... rn : Rn},o) = reference(R1, o.r1) || reference(R2, o.r2) || ... || reference(Rn, o.rn)
+</UL>
+Here each call to reference returns either <CODE>(Just o)</CODE> or <CODE>Nothing</CODE>.
+When we compute the reference for a table or a record then we pick 
+the reference for the first expression for which the recursive call
+gives us <CODE>Just</CODE>. If we get <CODE>Nothing</CODE> for
+all of them then the final result is <CODE>Nothing</CODE> too.
+
 <A NAME="toc25"></A>
 <H3>Printname definitions, printname cat and printname fun</H3>
 <P>
@@ -2927,7 +2995,7 @@ literals).
 <H3>Predefined concrete syntax operations</H3>
 <P>
 The following predefined operations are defined in the resource module
-<CODE>prelude/Predefined.gf</CODE>. Their implementations are defined as
+<CODE>prelude/Predef.gf</CODE>. Their implementations are defined as
 a part of the GF grammar compiler. 
 </P>
 <TABLE ALIGN="center" CELLPADDING="4" BORDER="1">
@@ -3031,6 +3099,26 @@ a part of the GF grammar compiler.
 <TD><CODE>(L : Type) -&gt; L -&gt; Str</CODE></TD>
 <TD>find the "first" string</TD>
 </TR>
+<TR>
+<TD><CODE>nonExist</CODE></TD>
+<TD><CODE>Str</CODE></TD>
+<TD>this is a special token marking<BR/>
+non-existing morphological forms</TD>
+</TR>
+<TR>
+<TD><CODE>BIND</CODE></TD>
+<TD><CODE>Str</CODE></TD>
+<TD>this is a special token marking<BR/>
+that the surrounding tokens should not<BR/>
+be separated by space</TD>
+</TR>
+<TR>
+<TD><CODE>SOFT_BIND</CODE></TD>
+<TD><CODE>Str</CODE></TD>
+<TD>this is a special token marking<BR/>
+that the surrounding tokens may not<BR/>
+be separated by space</TD>
+</TR>
 </TABLE>
 
 <P></P>
@@ -3427,24 +3515,25 @@ The reserved words used in GF are the following:
 <TD><CODE>lindef</CODE></TD>
 </TR>
 <TR>
+<TD><CODE>linref</CODE></TD>
 <TD><CODE>of</CODE></TD>
 <TD><CODE>open</CODE></TD>
 <TD><CODE>oper</CODE></TD>
-<TD><CODE>param</CODE></TD>
 </TR>
 <TR>
+<TD><CODE>param</CODE></TD>
 <TD><CODE>pre</CODE></TD>
 <TD><CODE>printname</CODE></TD>
 <TD><CODE>resource</CODE></TD>
-<TD><CODE>strs</CODE></TD>
 </TR>
 <TR>
+<TD><CODE>strs</CODE></TD>
 <TD><CODE>table</CODE></TD>
 <TD><CODE>transfer</CODE></TD>
 <TD><CODE>variants</CODE></TD>
-<TD><CODE>where</CODE></TD>
 </TR>
 <TR>
+<TD><CODE>where</CODE></TD>
 <TD><CODE>with</CODE></TD>
 <TD></TD>
 <TD></TD>
@@ -3773,6 +3862,11 @@ All other symbols are terminals.
 <TR>
 <TD></TD>
 <TD ALIGN="center"><B>|</B></TD>
+<TD><CODE>linref</CODE> <I>[Def]</I></TD>
+</TR>
+<TR>
+<TD></TD>
+<TD ALIGN="center"><B>|</B></TD>
 <TD><CODE>lin</CODE> <I>[Def]</I></TD>
 </TR>
 <TR>
author	kr.angelov <kr.angelov@gmail.com>	2013-11-12 16:05:02 +0000
committer	kr.angelov <kr.angelov@gmail.com>	2013-11-12 16:05:02 +0000
commit	0090b85002e4f609be7be107d9ac251cfd436afc (patch)
tree	42ceab8b330c6499f5297084857d577fb3d88c42 /doc
parent	709b2bb067b4c3c2316e608e35bc59172f1452d9 (diff)