extended Synopsis with categories, structural, and an example

lib/resource-1.0/doc/MkSynopsis.hs

@@ -5,16 +5,51 @@ main = do
   writeFile synopsis "GF Resource Grammar Library: Synopsis"
   append "Aarne Ranta"
   space
-  title "Syntax"
+  title "Categories"
   space
-  link "source" syntaxAPI
+  link "Source 1:" commonAPI
+  space
+  link "Source 2:" catAPI
+  space
+  cs1 <- getCats True commonAPI
+  cs2 <- getCats False catAPI
+  delimit $ cs1 ++ cs2
+  space
+  title "Syntax Rules"
+  space
+  link "Source:" syntaxAPI
   space
   rs <- getRules syntaxAPI
   delimit rs
   space
+  title "Structural Words"
+  space
+  link "Source:" structuralAPI
+  space
+  rs <- getRules structuralAPI
+  delimit rs
+  space
   mapM_ putParadigms paradigmFiles
+  space
+  title "Example Usage"
+  space
+  ss <- readFile "synopsis-example.txt" >>= return . lines
+  mapM_ append ss
+  space
   system $ "txt2tags -thtml --toc " ++ synopsis
 
+getCats isBeg file = do
+  ss <- readFile file >>= return . lines
+  return $ mkCatTable isBeg $ getrs [] ss
+ where
+   getrs rs ss = case ss of
+     ('-':'-':'.':_):_ -> reverse rs
+     [] -> reverse rs
+     ('-':'-':_):ss2 -> getrs rs ss2
+     s:ss2 -> case words s of
+       cat:";":"--":exp -> getrs ((cat,unwords expl, unwords (tail ex)):rs) ss2 where
+         (expl,ex) = span (/="e.g.") exp
+       _ -> getrs rs ss2
 
 getRules file = do
   ss <- readFile file >>= return . lines
@@ -28,6 +63,7 @@ getRules file = do
        _:_:"overload":_ -> getrs rs ss2
        _:":":_ -> getrs (layout s:rs) ss2
        _ -> getrs rs ss2
+   layout s = "  " ++ dropWhile isSpace s
 
 putParadigms (lang,file) = do
   title ("Paradigms for " ++ lang)
@@ -39,8 +75,6 @@ putParadigms (lang,file) = do
   delimit rs
   space
 
-layout s = "  " ++ dropWhile isSpace s
-
 
 mkTable rs = "|| Function  | Type  | Example  ||" : map (unwords . row . words) rs where
   row ws = ["|", name, "|", typ, "|", ex, "|"] where
@@ -53,8 +87,17 @@ mkTable rs = "|| Function  | Type  | Example  ||" : map (unwords . row . words)
       _ -> e
     filtype = filter (/=";")
 
+mkCatTable isBeg rs = 
+  (if isBeg then ("|| Category  | Explanation  | Example  ||" :) else id) 
+    (map mk1 rs) 
+ where
+  mk1 (name,typ,ex) = unwords ["|", ttf name, "|", typ, "|", ex, "|"]
+
 synopsis = "synopsis.txt"
+commonAPI = "../abstract/Common.gf"
+catAPI    = "../abstract/Cat.gf"
 syntaxAPI = "../api/Constructors.gf"
+structuralAPI = "../abstract/Structural.gf"
 paradigmFiles = [
   ("Danish", "../danish/ParadigmsDan.gf"),
   ("English", "../english/ParadigmsEng.gf"),
@@ -72,7 +115,8 @@ append s = appendFile synopsis ('\n':s)
 title s = append $ "=" ++ s ++ "="
 space = append "\n"
 delimit ss = mapM_ append ss
-link s f = append $ "[" ++ s ++ " " ++ f ++ "]"
+link s f = append $ s ++ " [``" ++ fa ++ "`` " ++ f ++ "]" where
+  fa = "http://www.cs.chalmers.se/~aarne/GF/lib/resource" ++ dropWhile (=='.') f
 
 ttf s = "``" ++ s ++ "``"
 itf s = "//" ++ s ++ "//"

lib/resource-1.0/doc/synopsis-example.txt

@@ -0,0 +1,49 @@
+The standard way of building an application has the following modules.
+
+An abstract syntax:
+```
+  abstract Music = {    
+  cat 
+    Kind, 
+    Property ;
+  fun 
+    PropKind : Kind -> Property -> Kind ; 
+    Song : Kind ;
+    American : Property ;
+  }
+```
+A domain lexicon interface:
+```
+  interface MusicLex = open Cat in {
+  oper
+    song_N : N ;
+    american_A : A ;
+  }
+```
+A functor on ``Syntax`` and the domain lexicon interface:
+```
+  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 ;
+  }
+```
+For each language, an instance of the domain lexicon:
+```
+  instance MusicLexGer of MusicLex = CatGer ** open ParadigmsGer in {    
+  oper
+    song_N = mkN "Lied" "Lieder" neuter ;
+    american_A = mkA "amerikanisch" ;
+  }
+```
+For each language, an instantiation of the functor:
+```
+  --# -path=.:present:prelude
+  concrete MusicGer of Music = MusicI with
+    (Syntax = SyntaxGer),
+    (MusicLex = MusicLexGer) ;
+```