version 3 of quick reference

3 files changed, 86 insertions, 79 deletions

diff --git a/doc/gf-reference.html b/doc/gf-reference.html
index f019a383d..c5c108760 100644
--- a/doc/gf-reference.html
+++ b/doc/gf-reference.html
@@ -7,45 +7,48 @@
 <P ALIGN="center"><CENTER><H1>GF Quick Reference</H1>
 <FONT SIZE="4">
 <I>Aarne Ranta</I><BR>
-Wed Mar 29 13:21:48 2006
+Tue Apr  4 09:41:30 2006
 </FONT></CENTER>
 
 <P></P>
 <HR NOSHADE SIZE=1>
 <P></P>
-    <UL>
-    <LI><A HREF="#toc1">A Quick Example</A>
-    <LI><A HREF="#toc2">Modules and files</A>
-    <LI><A HREF="#toc3">Judgements</A>
-    <LI><A HREF="#toc4">Types</A>
-    <LI><A HREF="#toc5">Expressions</A>
-    <LI><A HREF="#toc6">Pattern matching</A>
-    <LI><A HREF="#toc7">Sample library functions</A>
-    <LI><A HREF="#toc8">Flags</A>
-    <LI><A HREF="#toc9">File paths</A>
-    <LI><A HREF="#toc10">Alternative grammar formats</A>
-    <LI><A HREF="#toc11">References</A>
-    </UL>
+      <UL>
+      <LI><A HREF="#toc1">A complete example</A>
+      <LI><A HREF="#toc2">Modules and files</A>
+      <LI><A HREF="#toc3">Judgements</A>
+      <LI><A HREF="#toc4">Types</A>
+      <LI><A HREF="#toc5">Expressions</A>
+      <LI><A HREF="#toc6">Pattern matching</A>
+      <LI><A HREF="#toc7">Sample library functions</A>
+      <LI><A HREF="#toc8">Flags</A>
+      <LI><A HREF="#toc9">File paths</A>
+      <LI><A HREF="#toc10">Alternative grammar formats</A>
+      <LI><A HREF="#toc11">References</A>
+      </UL>
 
 <P></P>
 <HR NOSHADE SIZE=1>
 <P></P>
 <P>
-This is a quick reference on GF grammars.
+This is a quick reference on GF grammars. It aims to
+cover all forms of expression available when writing
+grammars. It assumes basic knowledge of GF, which
+can be acquired from the 
+<A HREF="http://www.cs.chalmers.se/~aarne/GF/doc/tutorial/">GF Tutorial</A>.
 Help on GF commands is obtained on line by the
-help command (<CODE>h</CODE>). 
+help command (<CODE>help</CODE>), and help on invoking
+GF with (<CODE>gf -help</CODE>).
 </P>
 <A NAME="toc1"></A>
-<H2>A Quick Example</H2>
+<H3>A complete example</H3>
 <P>
-This is a complete example, dividing a grammar
-into three files.
+This is a complete example of a GF grammar divided
+into three modules in files. The grammar recognizes the
+phrases <I>one pizza</I> and <I>two pizzas</I>.
 </P>
 <P>
-<CODE>abstract</CODE>, <CODE>concrete</CODE>, and <CODE>resource</CODE>.
-</P>
-<P>
-File <CODE>Order.gf</CODE>
+File <CODE>Order.gf</CODE>:
 </P>
 <PRE>
   abstract Order = {
@@ -83,7 +86,7 @@ File <CODE>Res.gf</CODE>:
   oper regNoun : Str -&gt; {s : Num =&gt; Str} =
     \dog -&gt; {s = table {
       Sg =&gt; dog ;
-      Pl =&gt; dog + "s"
+      _  =&gt; dog + "s"
       }
     } ;
   }
@@ -99,7 +102,7 @@ To use this example, do
 </PRE>
 <P></P>
 <A NAME="toc2"></A>
-<H2>Modules and files</H2>
+<H3>Modules and files</H3>
 <P>
 One module per file.
 File named <CODE>Foo.gf</CODE> contains module named
@@ -163,7 +166,7 @@ Comments have the forms
 <PRE>
   -- till the end of line
   {- any number of lines between -}
-  --# reserved for compiler pragmas
+  --# used for compiler pragmas
 </PRE>
 <P>
 A <CODE>concrete</CODE> can be opened like a <CODE>resource</CODE>.
@@ -181,7 +184,7 @@ An <CODE>abstract</CODE> can be opened like an <CODE>interface</CODE>.
 Any <CODE>concrete</CODE> of it then works as an <CODE>instance</CODE>.
 </P>
 <A NAME="toc3"></A>
-<H2>Judgements</H2>
+<H3>Judgements</H3>
 <PRE>
   cat C               -- declare category C
   cat C (x:A)(y:B x)  -- dependent category C
@@ -225,7 +228,7 @@ Judgements can also share RHS:
 </PRE>
 <P></P>
 <A NAME="toc4"></A>
-<H2>Types</H2>
+<H3>Types</H3>
 <P>
 Abstract syntax (in <CODE>fun</CODE>):
 </P>
@@ -259,7 +262,7 @@ Concrete syntax (in <CODE>lincat</CODE>):
 Resource (in <CODE>oper</CODE>): all those of concrete, plus
 </P>
 <PRE>
-  Tok              -- tokens (subset of Str)
+  Tok              -- tokens (subtype of Str)
   A -&gt; B           -- functions from A to B
   Int              -- integers
   Strs             -- list of prefixes (for pre)
@@ -268,11 +271,11 @@ Resource (in <CODE>oper</CODE>): all those of concrete, plus
 </PRE>
 <P>
 As parameter types, one can use any finite type:
-<CODE>param</CODE> constants <CODE>P</CODE>,
+<CODE>P</CODE> defined in <CODE>param P</CODE>,
 <CODE>Ints n</CODE>, and record types of parameter types.
 </P>
 <A NAME="toc5"></A>
-<H2>Expressions</H2>
+<H3>Expressions</H3>
 <P>
 Syntax trees = full function applications
 </P>
@@ -286,7 +289,7 @@ Syntax trees = full function applications
 Higher-Order Abstract syntax (HOAS): functions as arguments:
 </P>
 <PRE>
-  F a (\y -&gt; b)      -- : C if a : A, b : B (x : A), 
+  F a (\x -&gt; c)      -- : C if a : A, c : C (x : B), 
                         fun F : A -&gt; (B -&gt; C) -&gt; C
 </PRE>
 <P>
@@ -320,7 +323,7 @@ Tables
     _  =&gt; "mouse"      -- wildcard pattern
     }
   table {               
-    n =&gt; regn n "cat" ;-- variable pattern 
+    n =&gt; regn n "cat"  -- variable pattern 
     }
   table Num {...}      -- table given with arg. type
   table ["ox"; "oxen"] -- table as course of values
@@ -336,7 +339,6 @@ Records
 <PRE>
   {s = "Liz"; g = Fem} -- record in full form
   {s,t = "et"}         -- same as {s = "et";t= "et"}
-  
   {s = "Liz"} **       -- record extension: same as
     {g = Fem}             {s = "Liz" ; g = Fem}
   
@@ -392,14 +394,15 @@ Example:
 </PRE>
 <P></P>
 <A NAME="toc6"></A>
-<H2>Pattern matching</H2>
+<H3>Pattern matching</H3>
 <P>
 These patterns can be used in branches of <CODE>table</CODE> and
-<CODE>case</CODE> expressions.
+<CODE>case</CODE> expressions. Patterns are matched in the order in
+which they appear in the grammar.
 </P>
 <PRE>
   C                 -- atomic param constructor
-  C p q             -- param constr. appl- to patterns
+  C p q             -- param constr. applied to patterns
   x                 -- variable, matches anything
   _                 -- wildcard, matches anything
   "foo"             -- string
@@ -414,7 +417,7 @@ These patterns can be used in branches of <CODE>table</CODE> and
 </PRE>
 <P></P>
 <A NAME="toc7"></A>
-<H2>Sample library functions</H2>
+<H3>Sample library functions</H3>
 <PRE>
   -- lib/prelude/Predef.gf
   drop   : Int -&gt; Tok -&gt; Tok   -- drop prefix of length
@@ -446,7 +449,7 @@ These patterns can be used in branches of <CODE>table</CODE> and
 </PRE>
 <P></P>
 <A NAME="toc8"></A>
-<H2>Flags</H2>
+<H3>Flags</H3>
 <P>
 Flags can appear, with growing priority,
 </P>
@@ -480,13 +483,13 @@ Some common flags used in grammars:
   optimize=noexpand  for resource, if =all too big
 </PRE>
 <P>
-For the full set of values for <CODE>flag</CODE>, 
-use on-line <CODE>h -flag</CODE>.
+For the full set of values for <CODE>FLAG</CODE>, 
+use on-line <CODE>h -FLAG</CODE>.
 </P>
 <A NAME="toc9"></A>
-<H2>File paths</H2>
+<H3>File paths</H3>
 <P>
-Colon-separated lists of directories tried in the
+Colon-separated lists of directories searched in the
 given order: 
 </P>
 <PRE>
@@ -499,12 +502,12 @@ when invoked, or as flag to the <CODE>i</CODE> command.
 The prefix <CODE>--#</CODE> is used only in files.
 </P>
 <P>
-If the variabls <CODE>GF_LIB_PATH</CODE> is defined, its
+If the environment variabls <CODE>GF_LIB_PATH</CODE> is defined, its
 value is automatically prefixed to each directory to
 extend the original search path.
 </P>
 <A NAME="toc10"></A>
-<H2>Alternative grammar formats</H2>
+<H3>Alternative grammar formats</H3>
 <P>
 <B>Old GF</B> (before GF 2.0): 
 all judgements in any kinds of modules,
@@ -530,7 +533,7 @@ Rules must be one per line. The RHS can be empty.
 </PRE>
 <P>
 where the RHS is a regular expression of categories
-and quoted tokens: <CODE>"foo", T U, T|U, T*, T+, T?</CODE>, or empty.
+and quoted tokens: <CODE>"foo", CAT, T U, T|U, T*, T+, T?</CODE>, or empty.
 Rule labels are generated automatically.
 </P>
 <P>
@@ -560,7 +563,7 @@ are preprocessed by using a parser given by the flag
 and the result is written to <CODE>foo.gf</CODE>.
 </P>
 <A NAME="toc11"></A>
-<H2>References</H2>
+<H3>References</H3>
 <P>
 <A HREF="http://www.cs.chalmers.se/~aarne/GF/">GF Homepage</A>
 </P>
diff --git a/doc/gf-reference.pdf b/doc/gf-reference.pdf
index 4a43a8635..6eed355b8 100644
--- a/doc/gf-reference.pdf
+++ b/doc/gf-reference.pdf
diff --git a/doc/gf-reference.txt b/doc/gf-reference.txt
index 16e7b2378..d0c11ec34 100644
--- a/doc/gf-reference.txt
+++ b/doc/gf-reference.txt
@@ -9,19 +9,23 @@ Aarne Ranta
 %!target:html
 
 
-This is a quick reference on GF grammars.
+This is a quick reference on GF grammars. It aims to
+cover all forms of expression available when writing
+grammars. It assumes basic knowledge of GF, which
+can be acquired from the 
+[GF Tutorial http://www.cs.chalmers.se/~aarne/GF/doc/tutorial/].
 Help on GF commands is obtained on line by the
-help command (``h``). 
+help command (``help``), and help on invoking
+GF with (``gf -help``).
 
 
-==A Quick Example==
+===A complete example===
 
-This is a complete example, dividing a grammar
-into three files.
+This is a complete example of a GF grammar divided
+into three modules in files. The grammar recognizes the
+phrases //one pizza// and //two pizzas//.
 
-``abstract``, ``concrete``, and ``resource``.
-
-File ``Order.gf``
+File ``Order.gf``:
 ```
 abstract Order = {
 cat 
@@ -54,7 +58,7 @@ param Num = Sg | Pl ;
 oper regNoun : Str -> {s : Num => Str} =
   \dog -> {s = table {
     Sg => dog ;
-    Pl => dog + "s"
+    _  => dog + "s"
     }
   } ;
 }
@@ -69,7 +73,7 @@ To use this example, do
 
 
 
-==Modules and files==
+===Modules and files===
 
 One module per file.
 File named ``Foo.gf`` contains module named
@@ -122,7 +126,7 @@ Comments have the forms
 ```
 -- till the end of line
 {- any number of lines between -}
---# reserved for compiler pragmas
+--# used for compiler pragmas
 ```
 A ``concrete`` can be opened like a ``resource``.
 It is translated as follows:
@@ -138,7 +142,7 @@ Any ``concrete`` of it then works as an ``instance``.
 
 
 
-==Judgements==
+===Judgements===
 
 ```
 cat C               -- declare category C
@@ -179,7 +183,7 @@ fun f,g : A         -- same as fun f : A ; g : A
 ```
 
 
-==Types==
+===Types===
 
 Abstract syntax (in ``fun``):
 ```
@@ -208,7 +212,7 @@ Ints n           -- type of n first integers
 ```
 Resource (in ``oper``): all those of concrete, plus
 ``` 
-Tok              -- tokens (subset of Str)
+Tok              -- tokens (subtype of Str)
 A -> B           -- functions from A to B
 Int              -- integers
 Strs             -- list of prefixes (for pre)
@@ -216,12 +220,12 @@ PType            -- parameter type
 Type             -- any type
 ```
 As parameter types, one can use any finite type:
-``param`` constants ``P``,
+``P`` defined in ``param P``,
 ``Ints n``, and record types of parameter types.
 
 
 
-==Expressions==
+===Expressions===
 
 Syntax trees = full function applications
 ```
@@ -232,7 +236,7 @@ f a b              -- : C if fun f : A -> B -> C
 ```
 Higher-Order Abstract syntax (HOAS): functions as arguments:
 ```
-F a (\y -> b)      -- : C if a : A, b : B (x : A), 
+F a (\x -> c)      -- : C if a : A, c : C (x : B), 
                       fun F : A -> (B -> C) -> C
 ```
 Tokens and token lists
@@ -260,7 +264,7 @@ table {              -- by pattern matching
   _  => "mouse"      -- wildcard pattern
   }
 table {               
-  n => regn n "cat" ;-- variable pattern 
+  n => regn n "cat"  -- variable pattern 
   }
 table Num {...}      -- table given with arg. type
 table ["ox"; "oxen"] -- table as course of values
@@ -274,7 +278,6 @@ Records
 ```
 {s = "Liz"; g = Fem} -- record in full form
 {s,t = "et"}         -- same as {s = "et";t= "et"}
-
 {s = "Liz"} **       -- record extension: same as
   {g = Fem}             {s = "Liz" ; g = Fem}
 
@@ -318,13 +321,14 @@ lin F A B = {s = ["for all"] ++ A.s ++ B.$1 ++ B.s}
 ```
 
 
-==Pattern matching==
+===Pattern matching===
 
 These patterns can be used in branches of ``table`` and
-``case`` expressions.
+``case`` expressions. Patterns are matched in the order in
+which they appear in the grammar.
 ```
 C                 -- atomic param constructor
-C p q             -- param constr. appl- to patterns
+C p q             -- param constr. applied to patterns
 x                 -- variable, matches anything
 _                 -- wildcard, matches anything
 "foo"             -- string
@@ -338,7 +342,7 @@ p + "s"           -- sequence of two string patterns
 p*                -- repetition of a string pattern
 ```
 
-==Sample library functions==
+===Sample library functions===
 
 ```
 -- lib/prelude/Predef.gf
@@ -371,7 +375,7 @@ oper
 ```
 
 
-==Flags==
+===Flags===
 
 Flags can appear, with growing priority,
 - in files, judgement ``flags`` and without dash (``-``)
@@ -400,14 +404,14 @@ optimize=values    good for lexicon concrete
 optimize=all       usually good for resource
 optimize=noexpand  for resource, if =all too big
 ```
-For the full set of values for ``flag``, 
-use on-line ``h -flag``.
+For the full set of values for ``FLAG``, 
+use on-line ``h -FLAG``.
 
 
 
-==File paths==
+===File paths===
 
-Colon-separated lists of directories tried in the
+Colon-separated lists of directories searched in the
 given order: 
 ```
 --# -path=.:../abstract:../common:prelude
@@ -417,12 +421,12 @@ first line in the top file, as flag to ``gf``
 when invoked, or as flag to the ``i`` command.
 The prefix ``--#`` is used only in files.
 
-If the variabls ``GF_LIB_PATH`` is defined, its
+If the environment variabls ``GF_LIB_PATH`` is defined, its
 value is automatically prefixed to each directory to
 extend the original search path.
 
 
-==Alternative grammar formats==
+===Alternative grammar formats===
 
 **Old GF** (before GF 2.0): 
 all judgements in any kinds of modules,
@@ -442,7 +446,7 @@ Rules must be one per line. The RHS can be empty.
 S ::= (NP+ ("is" | "was") AP | V NP*) ;
 ```
 where the RHS is a regular expression of categories
-and quoted tokens: ``"foo", T U, T|U, T*, T+, T?``, or empty.
+and quoted tokens: ``"foo", CAT, T U, T|U, T*, T+, T?``, or empty.
 Rule labels are generated automatically.
 
 
@@ -465,7 +469,7 @@ are preprocessed by using a parser given by the flag
 and the result is written to ``foo.gf``.
 
 
-==References==
+===References===
 
 [GF Homepage http://www.cs.chalmers.se/~aarne/GF/]