updated resource doc intro with overloaded examples

1 files changed, 75 insertions, 64 deletions

diff --git a/doc/resource.txt b/doc/resource.txt
index a1c855fb7..ed2787ce3 100644
--- a/doc/resource.txt
+++ b/doc/resource.txt
@@ -25,13 +25,15 @@ Last update: %%date(%c)
 
 #CLEARPAGE
 
-This document is about the 
+This document is a guide for using the
 GF Resource Grammar Library. It presupposes knowledge of GF and its
-module system, knowledge that can be acquired e.g. from the GF
-tutorial. We start with an introduction to the library, and proceed to
+module system, knowledge that can be acquired e.g. from the 
+GF tutorial. 
+We start with an introduction to the library, and proceed to
 details with the goal of covering all that one needs to know 
 in order to use the library. 
-How to write one's own resource grammar (i.e. to implement the API for
+
+How to //write// one's own resource grammar (i.e. to implement the API for
 a new language), is covered by a separate Resource-HOWTO document (available in
 the www address below).
 
@@ -39,7 +41,7 @@ The main part of the document (the API documentation) is generated
 from the actual GF code by using the ``gfdoc`` tool. This documentation
 is also available on-line in HTML format in
 
-[``http://www.cs.chalmers.se/~aarne/GF/lib/resource-1.0/doc/`` http://www.cs.chalmers.se/~aarne/GF/lib/resource-1.0/doc/].
+[``http://www.cs.chalmers.se/~aarne/GF/lib/resource-1.2/doc/`` http://www.cs.chalmers.se/~aarne/GF/lib/resource-1.2/doc/].
 
 
 =Motivation=
@@ -55,7 +57,7 @@ is that of a skilled programmer with
 a practical knowledge of the target languages, but without
 theoretical knowledge about their grammars.
 Such a combination of
-skills is typical of programmers who want to localize
+skills is typical of programmers who, for instance, want to localize
 software to new languages.
 
 The current resource languages are
@@ -77,8 +79,11 @@ The first three letters (``Eng`` etc) are used in grammar module names.
 The Arabic and Catalan implementations are still incomplete, but 
 enough to be used in many applications.
 
-To give an example application, consider
-music playing devices. In the application,
+
+==An example application==
+
+To give an example application, consider a system for steering
+music playing devices by voice commands. In the application,
 we may have a semantical category ``Kind``, examples
 of ``Kind``s being ``Song`` and ``Artist``. In German, for instance, ``Song`` 
 is linearized into the noun "Lied", but knowing this is not
@@ -102,13 +107,13 @@ number, and case, and also depend on what determiner is used
 ("ein amerikanisches Lied" vs. "das amerikanische Lied"). All this
 variation is taken care of by the resource grammar function
 ```
-  fun AdjCN : AP -> CN -> CN
+  mkCN : AP -> CN -> CN
 ```
-(see the tables in the end of this document for the list of all resource grammar
+(see the table in the end of this document for the list of all resource grammar
 functions). The resource grammar implementation of the rule adding properties
 to kinds is
 ```
-  lin PropKind kind prop = AdjCN prop kind
+  lin PropKind kind prop = mkCN prop kind
 ```
 given that 
 ```
@@ -127,7 +132,7 @@ pick a different linearization of ``Song``,
   lin Song = mkN "chanson" feminine
 ```
 But to linearize ``PropKind``, we can use the very same rule as in German.
-The resource function ``AdjCN`` has different implementations in the two
+The resource function ``mkCN`` has different implementations in the two
 languages (e.g. a different word order in French), 
 but the application programmer need not care about the difference.
 
@@ -156,64 +161,67 @@ here is the complete implementation of a small system with songs and properties.
 The abstract syntax defines a "domain ontology":
 ```
   abstract Music = {
-    cat 
-      Kind, 
-      Property ;
-    fun 
-      PropKind : Kind -> Property -> Kind ; 
-      Song : Kind ;
-      American : Property ;
-    }
+    
+  cat 
+    Kind, 
+    Property ;
+  fun 
+    PropKind : Kind -> Property -> Kind ; 
+    Song : Kind ;
+    American : Property ;
+  }
 ```
 The concrete syntax is defined by a functor (parametrized module),
 independently of language, by opening
-two interfaces: the resource ``Grammar`` and an application lexicon.
-```
-  incomplete concrete MusicI of Music = open Grammar, MusicLex in {
-    lincat 
-      Kind = CN ;
-      Property = AP ;
-    lin
-      PropKind k p = AdjCN p k ;
-      Song = UseN song_N ;
-      American = PositA american_A ;
-    }
+two interfaces: the resource ``Syntax`` and an application lexicon.
+```
+  incomplete concrete MusicI of Music = open Syntax, MusicLex in {
+    
+  lincat 
+    Kind = CN ;
+    Property = AP ;
+  lin
+    PropKind k p = mkCN p k ;
+    Song = mkCN song_N ;
+    American = mkAP american_A ;
+  }
 ```
 The application lexicon ``MusicLex`` has an abstract syntax that extends
 the resource category system ``Cat``.
 ```
   abstract MusicLex = Cat ** {
-    fun
-      song_N : N ;
-      american_A : A ;
-    }
+    
+  fun
+    song_N : N ;
+    american_A : A ;
+  }
 ```
 Each language has its own concrete syntax, which opens the 
 inflectional paradigms module for that language:
 ```
   concrete MusicLexGer of MusicLex = 
-      CatGer ** open ParadigmsGer in {
-    lin
-      song_N = reg2N "Lied" "Lieder" neuter ;
-      american_A = regA "amerikanisch" ;
-    }
+      CatGer ** open ParadigmsGer in {    
+  lin
+    song_N = mkN "Lied" "Lieder" neuter ;
+    american_A = mkA "amerikanisch" ;
+  }
 
   concrete MusicLexFre of MusicLex = 
       CatFre ** open ParadigmsFre in {
-    lin
-      song_N = regGenN "chanson" feminine ;
-      american_A = regA "américain" ;
-    }
+  lin
+    song_N = mkN "chanson" feminine ;
+    american_A = mkA "américain" ;
+  }
 ```
 The top-level ``Music`` grammars are obtained by 
 instantiating the two interfaces of ``MusicI``:
 ```
   concrete MusicGer of Music = MusicI with
-    (Grammar = GrammarGer),
+    (Syntax = SyntaxGer),
     (MusicLex = MusicLexGer) ;
 
   concrete MusicFre of Music = MusicI with
-    (Grammar = GrammarFre),
+    (Syntax = SyntaxFre),
     (MusicLex = MusicLexFre) ;
 ```
 Both of these files can use the same ``path``, defined as
@@ -232,13 +240,13 @@ vocabulary and inflectional paradigms. For instance, Finnish is added as follows
 ```
   concrete MusicLexFin of MusicLex = 
       CatFin ** open ParadigmsFin in {
-    lin
-      song_N = regN "kappale" ;
-      american_A = regA "amerikkalainen" ;
-    }
+  lin
+    song_N = mkN "kappale" ;
+    american_A = mkA "amerikkalainen" ;
+  }
 
   concrete MusicFin of Music = MusicI with
-    (Grammar = GrammarFin),
+    (Syntax = SyntaxFin),
     (MusicLex = MusicLexFin) ;
 ```
 More work is of course needed if the language-independent linearizations in
@@ -251,13 +259,13 @@ before,
 ```
   concrete MusicLexEng of MusicLex = 
       CatEng ** open ParadigmsEng in {
-    lin
-      song_N = regN "song" ;
-      american_A = regA "American" ;
-    }
+  lin
+    song_N = mkN "song" ;
+    american_A = mkA "American" ;
+  }
 
   concrete MusicEng0 of Music = MusicI with
-    (Grammar = GrammarEng),
+    (Syntax = SyntaxEng),
     (MusicLex = MusicLexEng) ;
 ```
 The module ``MusicEng0`` would not be used on the top level, however, but
@@ -266,17 +274,20 @@ another module would be built on top of it, with a restricted import from
 except ``PropKind``, and
 gives its own definition of this function:
 ```
-  concrete MusicEng of Music = 
-      MusicEng0 - [PropKind] ** open GrammarEng in {
-    lin
-      PropKind k p = 
-        RelCN k (UseRCl TPres ASimul PPos 
-          (RelVP IdRP (UseComp (CompAP p)))) ;
-    }
+  concrete MusicEng of Music = MusicEng0 - [PropKind] ** 
+      open SyntaxEng in {
+  lin
+    PropKind k p = mkCN k (mkRS (mkRCl which_RP (mkVP p))) ;
+  }
 ```
 
+
 ==Lock fields==
 
+//This section is only relevant as a guide to error messages that have to do with lock fields, and can be skipped otherwise.//
+
+FIXME: this section may become obsolete.
+
 When the categories of the resource grammar are used
 in applications, a **lock field** is added to their linearization types.
 The lock field for a category ``C`` is a record field 
@@ -419,7 +430,7 @@ Below this top-level module exposing overloaded constructors,
 there are around 10 abstract modules, each defining constructors for
 a group of one or more related categories. For instance, the module
 ``Noun`` defines how to construct common nouns, noun phrases, and determiners.
-But these special modules are seldom needed by the users of the library.
+But these special modules are seldom or never needed by the users of the library.
 
 TODO: when are they needed?