cleaned up API comments for document

lib/resource-1.0/abstract/Adjective.gf

@@ -16,7 +16,7 @@ abstract Adjective = Cat ** {
     UseA2   : A2 -> A ;         -- divisible
 
 -- Sentence and question complements defined for all adjectival
--- phrases, although the semantics is only clear for some adjective.
+-- phrases, although the semantics is only clear for some adjectives.
  
     SentAP  : AP -> SC -> AP ;  -- great that she won, uncertain if she did
 

lib/resource-1.0/abstract/Cat.gf

@@ -7,7 +7,7 @@
 -- it is enough that both $Verb$ and $Noun$ use the same type $NP$,
 -- which is given here in $Cat$.
 -- 
--- Some categories are inherited from [Common Common.html].
+-- Some categories are inherited from [``Common`` Common.html].
 -- The reason they are defined there is that they have the same
 -- implementation in all languages in the resource (typically,
 -- just a string). These categories are
@@ -75,7 +75,7 @@ abstract Cat = Common ** {
     CN ;    -- common noun (without determiner)    e.g. "red house"
     NP ;    -- noun phrase (subject or object)     e.g. "the red house"
     Pron ;  -- personal pronoun                    e.g. "she"
-    Det ;   -- determiner phrase                   e.g. "all the seven"
+    Det ;   -- determiner phrase                   e.g. "those seven"
     Predet; -- predeterminer (prefixed Quant)      e.g. "all"
     QuantSg;-- quantifier ('nucleus' of sing. Det) e.g. "every"
     QuantPl;-- quantifier ('nucleus' of plur. Det) e.g. "many"

lib/resource-1.0/abstract/Common.gf

@@ -4,12 +4,12 @@
 -- ${s : Str}$ in all languages. 
 
 -- Moreover, this module defines the abstract parameters of tense, polarity, and
--- anteriority, which are used in [Phrase Phrase.html] to generate different
--- forms of sentences. Together they give 2 x 4 x 4 = 16 sentence forms.
+-- anteriority, which are used in [``Phrase`` Phrase.html] to generate different
+-- forms of sentences. Together they give 4 x 2 x 2 = 16 sentence forms.
 
 -- These tenses are defined for all languages in the library. More tenses
 -- can be defined in the language extensions, e.g. the "passé simple" of
--- Romance languages.
+-- Romance languages in [``ExtraRomance`` ../romance/ExtraRomance.gf].
 
 abstract Common = {
 
@@ -17,25 +17,25 @@ abstract Common = {
 
 --2 Top-level units
 
--- Constructed in [Text Text.html]: $Text$.
+-- Constructed in [``Text`` Text.html]: $Text$.
 
     Text ;  -- text consisting of several phrases  e.g. "He is here. Why?"
 
--- Constructed in [Phrase Phrase.html]:
+-- Constructed in [``Phrase`` Phrase.html]:
 
     Phr ;   -- phrase in a text                    e.g. "but be quiet please"
     Utt ;   -- sentence, question, word...         e.g. "be quiet"
     Voc ;   -- vocative or "please"                e.g. "my darling"
     PConj ; -- phrase-beginning conj.              e.g. "therefore"
 
--- Constructed in [Sentence Sentence.html]:
+-- Constructed in [``Sentence`` Sentence.html]:
 
     SC ;    -- embedded sentence or question       e.g. "that it rains"
 
 --2 Adverbs
 
--- Constructed in [Adverb Adverb.html].  
--- Many adverbs are constructed in [Structural Structural.html].
+-- Constructed in [``Adverb`` Adverb.html].  
+-- Many adverbs are constructed in [``Structural`` Structural.html].
 
     Adv ;   -- verb-phrase-modifying adverb,       e.g. "in the house"
     AdV ;   -- adverb directly attached to verb    e.g. "always"

lib/resource-1.0/abstract/Conjunction.gf

@@ -7,9 +7,10 @@
 -- - distributed conjunction: both X,...,X and X
 --
 --
--- *Note*. This module uses right-recursive lists. If backward
--- compatibility with API 0.9 is needed, use
--- [SeqConjunction SeqConjunction.html].
+-- $VP$ conjunctions are not covered here, because their applicability
+-- depends on language. Some special cases are defined in 
+-- [``Extra`` ../abstract/Extra.gf].
+
 
 abstract Conjunction = Cat ** {
 
@@ -44,3 +45,8 @@ abstract Conjunction = Cat ** {
   --  BaseC : C -> C   -> [C] ;  -- for C = S, AP, NP, Adv
   --  ConsC : C -> [C] -> [C] ;
 }
+
+--.
+-- *Note*. This module uses right-recursive lists. If backward
+-- compatibility with API 0.9 is needed, use
+-- [SeqConjunction SeqConjunction.html].

lib/resource-1.0/abstract/Grammar.gf

@@ -1,7 +1,7 @@
 --1 Grammar: the Main Module of the Resource Grammar
 
--- This grammar a collection of the different grammar modules,
--- To test the resource, import [Lang Lang.html], which also contains
+-- This grammar is a collection of the different grammar modules,
+-- To test the resource, import [``Lang`` Lang.html], which also contains
 -- a lexicon.
 
 abstract Grammar = 

lib/resource-1.0/abstract/Lang.gf

@@ -2,7 +2,7 @@
 
 -- This grammar is for testing the resource as included in the
 -- language-independent API, consisting of a grammar and a lexicon.
--- The grammar without a lexicon is [Grammar Grammar.html],
+-- The grammar without a lexicon is [``Grammar`` Grammar.html],
 -- which may be more suitable to open in applications.
 
 abstract Lang = 

lib/resource-1.0/abstract/Noun.gf

@@ -15,7 +15,7 @@ abstract Noun = Cat ** {
     UsePN   : PN -> NP ;          -- John
     UsePron : Pron -> NP ;        -- he
 
--- Pronouns are defined in the module [Structural Structural.html].
+-- Pronouns are defined in the module [``Structural`` Structural.html].
 
 -- A noun phrase already formed can be modified by a $Predet$erminer.
 
@@ -45,7 +45,8 @@ abstract Noun = Cat ** {
 
 -- Pronouns have possessive forms. Genitives of other kinds
 -- of noun phrases are not given here, since they are not possible
--- in e.g. Romance languages.
+-- in e.g. Romance languages. They can be found in
+-- [``Extra`` ../abstract/Extra.gf].
 
     PossPron : Pron -> Quant ;    -- my (house)
 
@@ -111,7 +112,7 @@ abstract Noun = Cat ** {
     UseN3   : N3 -> CN ;          -- flight
 
 -- Nouns can be modified by adjectives, relative clauses, and adverbs
--- (the last rule will give rise to many 'PP attachement' ambiguities
+-- (the last rule will give rise to many 'PP attachment' ambiguities
 -- when used in connection with verb phrases).
 
     AdjCN   : AP -> CN  -> CN ;   -- big house

lib/resource-1.0/abstract/Numeral.gf

@@ -6,13 +6,16 @@
 -- which defines numerals for 88 languages.
 -- The resource grammar implementations add to this inflection (if needed)
 -- and ordinal numbers.
-
--- *Note*. Number 1 as defined 
+--
+-- *Note* 1. Number 1 as defined 
 -- in the category $Numeral$ here should not be used in the formation of
 -- noun phrases, and should therefore be removed. Instead, one should use
 -- [Structural Structural.html]$.one_Quant$. This makes the grammar simpler
 -- because we can assume that numbers form plural noun phrases.
-
+--
+-- *Note* 2. The implementations introduce spaces between
+-- parts of a numeral, which is often incorrect - more work on
+-- (un)lexing is needed to solve this problem.
 
 abstract Numeral = Cat ** {
 

lib/resource-1.0/abstract/Question.gf

@@ -24,6 +24,6 @@ abstract Question = Cat ** {
 
 
 -- More $IP$, $IDet$, and $IAdv$ are defined in
--- [Structural Structural.html].
+-- [``Structural`` Structural.html].
 
 }

lib/resource-1.0/abstract/Relative.gf

@@ -9,8 +9,9 @@ abstract Relative = Cat ** {
 
     RelCl    : Cl -> RCl ;            -- such that John loves her
 
--- The more proper ways are from a verb phrase (formed in [Verb Verb.html]) 
--- or a sentence with a missing noun phrase (formed in [Sentence Sentence.html]).
+-- The more proper ways are from a verb phrase 
+-- (formed in [``Verb`` Verb.html]) or a sentence 
+-- with a missing noun phrase (formed in [``Sentence`` Sentence.html]).
 
     RelVP    : RP -> VP -> RCl ;      -- who loves John
     RelSlash : RP -> Slash -> RCl ;   -- whom John loves

lib/resource-1.0/abstract/Sentence.gf

@@ -6,7 +6,8 @@ abstract Sentence = Cat ** {
 
 -- The $NP VP$ predication rule form a clause whose linearization
 -- gives a table of all tense variants, positive and negative.
--- Clauses are converted to $S$ (with fixed tense) in [Tensed Tensed.html].
+-- Clauses are converted to $S$ (with fixed tense) with the
+-- $UseCl$ function below.
 
   fun
     PredVP    : NP -> VP -> Cl ;         -- John walks
@@ -53,7 +54,7 @@ abstract Sentence = Cat ** {
 
 -- These are the 2 x 4 x 4 = 16 forms generated by different
 -- combinations of tense, polarity, and
--- anteriority, which are defined in [Tense Tense.html].
+-- anteriority, which are defined in [``Common`` Common.html].
 
   fun
     UseCl  : Tense -> Ant -> Pol -> Cl  -> S ;

lib/resource-1.0/abstract/Structural.gf

@@ -2,8 +2,9 @@
 -- 
 -- Here we have some words belonging to closed classes and appearing
 -- in all languages we have considered.
--- Sometimes they are not really meaningful, e.g. $we_Pron$ in Spanish
--- should be replaced by masculine and feminine variants.
+-- Sometimes more distinctions are needed, e.g. $we_Pron$ in Spanish
+-- should be replaced by masculine and feminine variants, found in
+-- [``ExtraSpa`` ../spanish/ExtraSpa.gf].
 
 abstract Structural = Cat ** {