improved absfuns.html generation, added links, improved comments in source files to give better documentation

lib/doc/AbsFunDoc.hs

@@ -16,11 +16,13 @@ main = do
   deps <- readFile "../src/uddeps.labels" >>= return . lines
   let depmap = M.fromList [(fun,deps) | fun:deps <- map words deps]
   let rows = sort $ filter (flip S.notMember hiddenModules . last) $ map (mkRow depmap) (map words funs)
-  let entries = map sepFields rows
+  let entries = map (sepFields . addLink) rows
-  putStrLn $ "GF RGL Functions"
+  putStrLnIf $ "GF RGL Functions"
-  putStrLn $ "generated by lib/src/doc/AbsFunFoc.hs"
+  putStrLnIf $ "generated by lib/src/doc/AbsFunFoc.hs"
-  putStrLn $ ""
+  putStrLnIf $ "%%date"
-  putStrLn $ sepFields ["Function","Type","Example","Dependencies","Module"]
+  putStrLnIf $ ""
+  putStrLnIf $ "Functions in this table have links, e.g. http://www.grammaticalframework.org/lib/doc/absfuns.html#PredVP"
+  putStrLn $ sepFields ["**Function**","**Type**","**Example**","**Dependencies**","**Module**"]
   putStrLn $ unlines entries
 
 
@@ -29,14 +31,27 @@ hiddenModules = S.fromList
    "Documentation","Lexicon","NumeralTransfer","Terminology","Transfer","MarkHTML","Markup","ERROR"] ----
 
 mkRow depmap ws = case ws of
-  file:fun:":":typecomment -> fun : getTypeComment typecomment ++ [getDep fun, getModule file]
+  file:fun:":":typecomment -> named fun : getTypeComment typecomment ++ [getDep fun, getModule file]
   _ -> ["ERROR"]
  where
    getModule = reverse . takeWhile (/='/') . tail . dropWhile (/='.') . reverse -- ../src/abstract/Adverb.gf: --> Adverb
    getTypeComment ws = case span (/= ";") ws of
-     (ty,rest) -> [unwords ty, unwords (drop 2 rest)]  -- PredVP    : NP -> VP -> Cl ; -- John walks
+     (ty,rest) -> [unwords ty, italics (unwords (drop 2 rest))]  -- PredVP    : NP -> VP -> Cl ; -- John walks
    getDep fun = maybe "-" (unwords . takeWhile (/="--")) $ M.lookup fun depmap
 
--- sepFields = concat . intersperse "\t"
+-- for html (via txt2tags) generation
 sepFields fs = "| " ++ concat (intersperse " | " fs) ++ " |"
+named f = f ++ "''<a name=\"" ++ f ++ "\"></a>''"
+italics e = "//" ++ map (\c -> case c of '[' -> '(' ; ']'->')'; _ -> c) e ++ "//"
+putStrLnIf = putStrLn
+addLink fs =
+  let m = last fs ; abstract = case m of "Extensions" -> "translator/" ; _ -> "abstract/"
+  in init fs ++ ["[" ++ m ++ " ../src/" ++ abstract ++ m ++ ".gf]"]
+
+-- for tab separated generation
+-- sepFields = concat . intersperse "\t"
+-- named f = f
+-- italics e = e
+-- putStrLnIf = return ()
+-- addLink fs = fs
 

lib/src/abstract/Conjunction.gf

@@ -17,15 +17,15 @@ abstract Conjunction = Cat ** {
 --2 Rules
 
   fun
-    ConjS    : Conj -> [S] -> S ;       -- "he walks and she runs"
+    ConjS    : Conj -> [S] -> S ;       -- he walks and she runs
-    ConjRS   : Conj -> [RS] -> RS ;     -- "who walks and whose mother runs"
+    ConjRS   : Conj -> [RS] -> RS ;     -- who walks and whose mother runs
-    ConjAP   : Conj -> [AP] -> AP ;     -- "cold and warm"
+    ConjAP   : Conj -> [AP] -> AP ;     -- cold and warm
-    ConjNP   : Conj -> [NP] -> NP ;     -- "she or we"
+    ConjNP   : Conj -> [NP] -> NP ;     -- she or we
-    ConjAdv  : Conj -> [Adv] -> Adv ;   -- "here or there"
+    ConjAdv  : Conj -> [Adv] -> Adv ;   -- here or there
-    ConjAdV  : Conj -> [AdV] -> AdV ;
+    ConjAdV  : Conj -> [AdV] -> AdV ;   -- always or sometimes
-    ConjIAdv : Conj -> [IAdv] -> IAdv ; -- "where and with whom"
+    ConjIAdv : Conj -> [IAdv] -> IAdv ; -- where and with whom
-    ConjCN   : Conj -> [CN] -> CN ;     -- "man and woman"
+    ConjCN   : Conj -> [CN] -> CN ;     -- man and woman
-    ConjDet  : Conj -> [DAP] -> Det ;   -- "his or her"
+    ConjDet  : Conj -> [DAP] -> Det ;   -- his or her
 
 --2 Categories
 

lib/src/abstract/Noun.gf

@@ -20,7 +20,7 @@ abstract Noun = Cat ** {
 
 -- A noun phrase already formed can be modified by a $Predet$erminer.
 
-    PredetNP : Predet -> NP -> NP; -- only the man 
+    PredetNP : Predet -> NP -> NP ; -- only the man 
 
 -- A noun phrase can also be postmodified by the past participle of a
 -- verb, by an adverb, or by a relative clause
@@ -50,9 +50,9 @@ abstract Noun = Cat ** {
 -- the "kernel" of a determiner. It is, however, the $Num$ that determines
 -- the inherent number.
 
-    NumSg   : Num ;
+    NumSg   : Num ;  -- [no numeral, but marked as singular]
-    NumPl   : Num ;
+    NumPl   : Num ;  -- [no numeral, but marked as plural]
-    NumCard : Card -> Num ;
+    NumCard : Card -> Num ; -- one/five [explicit numeral]
 
 -- $Card$ consists of either digits or numeral words.
 
@@ -82,8 +82,8 @@ abstract Noun = Cat ** {
 -- neatly distinct words (Spanish "un, unos ; el, los") but also without
 -- any particular word (Finnish; Swedish definites).
 
-    IndefArt   : Quant ;
+    IndefArt   : Quant ;  -- a/an
-    DefArt     : Quant ;
+    DefArt     : Quant ;  -- the
 
 -- Nouns can be used without an article as mass nouns. The resource does
 -- not distinguish mass nouns from other common nouns, which can result

lib/src/abstract/Numeral.gf

@@ -27,7 +27,7 @@ cat
   Sub1000000 ;  -- 1..999999
 
 data 
-  num : Sub1000000 -> Numeral ;
+  num : Sub1000000 -> Numeral ; -- 123456 [coercion to top category]
 
   n2, n3, n4, n5, n6, n7, n8, n9 : Digit ;
 

lib/src/abstract/Phrase.gf

@@ -36,13 +36,13 @@ abstract Phrase = Cat ** {
 -- The phrasal conjunction is optional. A sentence conjunction
 -- can also be used to prefix an utterance.
 
-    NoPConj   : PConj ;                      
+    NoPConj   : PConj ;                     -- [plain phrase without conjunction in front]
     PConjConj : Conj -> PConj ;             -- and
 
 -- The vocative is optional. Any noun phrase can be made into vocative,
 -- which may be overgenerating (e.g. "I").
 
-    NoVoc   : Voc ;
+    NoVoc   : Voc ;                         -- [plain phrase without vocative]
     VocNP   : NP -> Voc ;                   -- my friend
 
 }

lib/src/abstract/Sentence.gf

@@ -57,10 +57,10 @@ abstract Sentence = Cat ** {
 -- anteriority, which are defined in [``Common`` Common.html].
 
   fun
-    UseCl    : Temp -> Pol -> Cl  -> S ;
+    UseCl    : Temp -> Pol -> Cl  -> S ;   -- she had not slept
-    UseQCl   : Temp -> Pol -> QCl -> QS ;
+    UseQCl   : Temp -> Pol -> QCl -> QS ;  -- who had not slept
-    UseRCl   : Temp -> Pol -> RCl -> RS ;
+    UseRCl   : Temp -> Pol -> RCl -> RS ;  -- that had not slept
-    UseSlash : Temp -> Pol -> ClSlash -> SSlash ;
+    UseSlash : Temp -> Pol -> ClSlash -> SSlash ; -- (that) she had not seen
 
 -- An adverb can be added to the beginning of a sentence, either with comma ("externally")
 -- or without:

lib/src/abstract/Symbol.gf

@@ -12,7 +12,7 @@ fun
   SymbPN   : Symb -> PN ;                -- x
   IntPN    : Int -> PN ;                 -- 27
   FloatPN  : Float -> PN ;               -- 3.14159
-  NumPN    : Card -> PN ;
+  NumPN    : Card -> PN ;                -- twelve [as proper name]
   CNNumNP  : CN -> Card -> NP ;          -- level five ; level 5
   CNSymbNP : Det -> CN -> [Symb] -> NP ; -- (the) (2) numbers x and y
 
@@ -37,7 +37,7 @@ cat
   [Symb]{2} ;
 
 fun
-  MkSymb : String -> Symb ;
+  MkSymb : String -> Symb ;     -- foo [making a symbol from a string]
 
 --2 Obsolescent
 

lib/src/abstract/Tense.gf

@@ -11,12 +11,15 @@
 abstract Tense = Common ** {
 
   fun
-    TTAnt : Tense -> Ant -> Temp ;
+    TTAnt : Tense -> Ant -> Temp ;  -- [combination of tense and anteriority, e.g. past anterior]
 
-    PPos, PNeg : Pol ;           -- I sleep/don't sleep
+    PPos : Pol ;           -- I sleep  [positive polarity]
+    PNeg : Pol ;           -- I don't sleep [negative polarity]
 
-    TPres  : Tense ;                
+    TPres  : Tense ;             -- I sleep/have slept [present]  
-    ASimul : Ant ;
+    ASimul : Ant ;               -- I sleep/slept [simultaneous, not compound]
-    TPast, TFut, TCond : Tense ; -- I slept/will sleep/would sleep --# notpresent
+    TPast  : Tense ;             -- I slept [past, "imperfect"]      --# notpresent
-    AAnter : Ant ;               -- I have slept                   --# notpresent
+    TFut   : Tense ;             -- I will sleep [future] --# notpresent
+    TCond  : Tense ;             -- I would sleep [conditional] --# notpresent
+    AAnter : Ant ;               -- I have slept/had slept [anterior, "compound", "perfect"] --# notpresent
 }

lib/src/abstract/Text.gf

@@ -7,7 +7,7 @@
 abstract Text = Common ** {
 
   fun
-    TEmpty     : Text ;                 --
+    TEmpty     : Text ;                 -- [empty text, no sentences]
     TFullStop  : Phr -> Text -> Text ;  -- John walks. ...
     TQuestMark : Phr -> Text -> Text ;  -- Are they here? ...
     TExclMark  : Phr -> Text -> Text ;  -- Let's go! ...

lib/src/translator/Extensions.gf

@@ -13,13 +13,13 @@ cat
   [VPS] {2} ;
 
 fun
-  MkVPI : VP -> VPI ;
+  MkVPI : VP -> VPI ;               -- to walk
-  ConjVPI : Conj -> [VPI] -> VPI ;
+  ConjVPI : Conj -> [VPI] -> VPI ;  -- to walk and drink beer
-  ComplVPIVV : VV -> VPI -> VP ;
+  ComplVPIVV : VV -> VPI -> VP ;    -- want to walk and drink beer
 
-  MkVPS : Temp -> Pol -> VP -> VPS ;
+  MkVPS : Temp -> Pol -> VP -> VPS ;  -- had walked
-  ConjVPS : Conj -> [VPS] -> VPS ;
+  ConjVPS : Conj -> [VPS] -> VPS ;    -- had walked and drank beer
-  PredVPS : NP -> VPS -> S ;
+  PredVPS : NP -> VPS -> S ;          -- I had walked and drank beer
 
 ---- merge VPS and VPI
 ----            MkVPS, BaseVPS, ConsVPS, ConjVPS, PredVPS,
@@ -63,11 +63,11 @@ fun
   PastPartAP      : VPSlash -> AP ;         -- lost (opportunity) ; (opportunity) lost in space
   PastPartAgentAP : VPSlash -> NP -> AP ;   -- (opportunity) lost by the company
 
-  UseQuantPN : Quant -> PN -> NP;  -- this John
+  UseQuantPN : Quant -> PN -> NP ;  -- this John
     
 ---- merge with IdRP?
-    that_RP : RP ;
+    that_RP : RP ;    -- that [relative pronoun]
-    who_RP : RP ;
+    who_RP : RP ;     -- who [relative pronoun]
     EmptyRelSlash : ClSlash -> RCl ;            -- (the city) he lives in
 
 ---- overgenerating?
@@ -80,7 +80,7 @@ fun
 	
 ---- move to standard RGL?
     AdAdV       : AdA -> AdV -> AdV ;           -- almost always
-    UttAdV      : AdV -> Utt;                   -- always!
+    UttAdV      : AdV -> Utt ;                  -- always(!)
     PositAdVAdj : A -> AdV ;                    -- (that she) positively (sleeps)
 
     CompS       : S -> Comp ;                   -- (the fact is) that she sleeps