[[project @ 2002-12-16 22:32:30 by as49] as49**20021216223231 Documentation update. ] { adddir ./doc addfile ./doc/Makefile addfile ./doc/gtk2hs.xml addfile ./doc/mogul.xml hunk ./ChangeLog 2 + + * gendoc/PrettyLib.hs: convert from PackedString to normal String + + * gendoc/Update.hs, gendoc/XMLwrite.hs: add hyperlinks between + from synopsis and tried to link arguments to types. + + * doc/Makefile doc/gtk2hs.xml doc/mogul.xml: Added documentation. hunk ./doc/Makefile 1 +TOP = .. +HERE = doc/ + +include $(TOP)/mk/config.mk + +EMPTY = +SPACE = $(EMPTY) $(EMPTY) + +GENDOC = gendoc/gendoc + +SUBDIRS_GTK = gtk/abstract gtk/buttons gtk/display gtk/ gtk/embedding \ + gtk/entry gtk/general gtk/layout gtk/menuComboToolbar \ + gtk/misc gtk/multiline gtk/ornaments gtk/scrolling \ + gtk/treeList gtk/windows gtk/gdk gtk/glib gtk/pango \ + compat + +SUBDIRS_MOGUL = mogul $(SUBDIRS_GTK) + +TOPLEVEL_GTK = Gtk.hs + +TOPLEVEL_MOGUL = Mogul.hs + +EXCLUDE_GTK = Foreign Monad LocalData Exception IORef LocalControl \ + Bits UTFCForeign Signal Char Maybe Prelude System + +EXCLUDE_MOGUL = $(EXCLUDE_GTK) + +OUTPUT_GTK = referenceGTK.xml + +OUTPUT_MOGUL = referenceMOGUL.xml + +OPTIONS_GTK = + +OPTIONS_MOGUL = + +OUTPUT_FO_GTK = gtk2hs.fo + +OUTPUT_FO_MOGUL = mogul.fo + +INPUT_GTK = gtk2hs.xml + +INPUT_MOGUL = mogul.xml + +.PRECIOUS: $(OUTPUT_GTK) $(OUTPUT_MOGUL) + +reference%.xml : $(TOP)/$(GENDOC) + $(strip $(TOP)/$(GENDOC) -o $(OUTPUT_$*) \ + -I$(subst $(SPACE),:,$(strip $(addprefix $(TOP)/,$(SUBDIRS_$*)))) \ + $(addprefix -x,$(EXCLUDE_$*)) $(OPTIONS_$*) $(TOPLEVEL_$*)) + +html% : $(OUTPUT_GTK) $(OUTPUT_MOGUL) + $(strip SGML_CATALOG_FILES=$(CATALOGS) $(XSLTPROC) --catalogs \ + -nonet $(XSLTHTML) $(INPUT_$*)) + mv *.html $* + +fo% : $(OUTPUT_$*) + $(strip SGML_CATALOG_FILES=$(CATALOGS) $(XSLTPROC) --catalogs \ + -o $(OUTPUT_$*) -nonet $(XSLTFO) $(INPUT_$*)) + mv *.fo $* + +.PHONY: $(TOP)/$(GENDOC) + +$(TOP)/$(GENDOC) : + $(MAKE) -C $(TOP)/$(dir $(GENDOC)) + +all : htmlGTK htmlMOGUL + + hunk ./doc/gtk2hs.xml 1 + + +]> + +The Haskell Gtk Implementor's Reference +Gtk - Haskell API + &refGTK; + + hunk ./doc/mogul.xml 1 + + +]> + + + + A Haskell binding for the Gimp Toolkit + AxelSimon + 2002Axel Simon + + +GUI Elements + +Trees and Lists + +
Storage and Display +
+ +
Representing nested structures +
+ +
Editing +
+ +
Sorting +
+ +
Storing custom data +
+ + + + +Beyond Widgets +Internationalization + + + + + +Reference +The Mogul API + +&refMOGUL; + + + + + hunk ./gendoc/PrettyLib.hs 27 -import Data.PackedString - hunk ./gendoc/PrettyLib.hs 38 -text :: PackedString -> Doc +text :: String -> Doc hunk ./gendoc/PrettyLib.hs 41 -ptext :: String -> Doc -ptext = TEXT . packString - hunk ./gendoc/PrettyLib.hs 73 -doubleQuotes s = ptext ('"' : s ++ "\"") +doubleQuotes s = text ('"' : s ++ "\"") hunk ./gendoc/PrettyLib.hs 76 -parens doc = ptext "(" <> doc <> ptext ")" +parens doc = text "(" <> doc <> text ")" hunk ./gendoc/PrettyLib.hs 79 -brackets doc = ptext "[" <> doc <> ptext "]" +brackets doc = text "[" <> doc <> text "]" hunk ./gendoc/PrettyLib.hs 82 -braces doc = ptext "{" <> doc <> ptext "}" +braces doc = text "{" <> doc <> text "}" hunk ./gendoc/PrettyLib.hs 85 -string s = ptext ('\"' : s ++ "\"") +string s = text ('\"' : s ++ "\"") hunk ./gendoc/PrettyLib.hs 100 - | TEXT PackedString | DELIMITER String | FDELIMITER String | LINE + | TEXT String | DELIMITER String | FDELIMITER String | LINE hunk ./gendoc/PrettyLib.hs 138 - go i (TEXT s) rest = Text (unpackPS s) (lengthPS s) : rest + go i (TEXT s) rest = Text s (length s) : rest hunk ./gendoc/Update.hs 93 - modSymTab=addToFM st fun (si { symArgs=merge pats args }) }) + modSymTab=addToFM st fun (si { symArgs=zipWith (:) pats + (if args==[] then repeat [] else args) }) }) hunk ./gendoc/Update.hs 96 - where + +{- where hunk ./gendoc/Update.hs 105 +-} hunk ./gendoc/XMLwrite.hs 6 +import Maybe (fromMaybe) +import List (transpose) hunk ./gendoc/XMLwrite.hs 20 -type Value = PackedString +type Value = String hunk ./gendoc/XMLwrite.hs 29 - value :: Value } + value :: String } hunk ./gendoc/XMLwrite.hs 32 --- deriving Show +-- Escape characters in plain text. +-- +escape ('<':xs) = '&':'l':'t':';':escape xs +escape ('>':xs) = '&':'g':'t':';':escape xs +escape ('"':xs) = '&':'q':'u':'o':'t':';':escape xs +escape ('[':xs) = '&':'l':'s':'q':'b':';':escape xs +escape (']':xs) = '&':'r':'s':'q':'b':';':escape xs +escape (x:xs) = x:escape xs +escape [] = [] + hunk ./gendoc/XMLwrite.hs 49 - hunk ./gendoc/XMLwrite.hs 51 -xmlToDoc (Plain value) = text value +xmlToDoc (Plain value) = text (escape value) hunk ./gendoc/XMLwrite.hs 54 - lStart <> text (packString name) <> + lStart <> text name <> hunk ./gendoc/XMLwrite.hs 60 - lStart <> text (packString name) <> + lStart <> text name <> hunk ./gendoc/XMLwrite.hs 69 - lStop <> text (packString name) <> rStart + lStop <> text name <> rStart hunk ./gendoc/XMLwrite.hs 76 -attrToDoc (Attribute name val) = text (packString name) <> equals <> +attrToDoc (Attribute name val) = text name <> equals <> hunk ./gendoc/XMLwrite.hs 80 -lStart = text (packString "<") -lStop = text (packString "") -rStop = text (packString "/>") -equals = text (packString "=") +lStart = text "<" +lStop = text "" +rStop = text "/>" +equals = text "=" hunk ./gendoc/XMLwrite.hs 89 - q = text (packString "\"") + q = text "\"" hunk ./gendoc/XMLwrite.hs 99 - Element "function" [] [Plain (packString "textViewNewWithAttributes")], + Element "function" [] [Plain "textViewNewWithAttributes"], hunk ./gendoc/XMLwrite.hs 101 - Element "hatycon" [] [Plain (packString "Int")], - Element "hatyvar" [] [Plain (packString "cr")]]] + Element "hatycon" [] [Plain "Int"], + Element "hatyvar" [] [Plain "cr"]]] hunk ./gendoc/XMLwrite.hs 107 -hTypeToXML (TyCon con) = Element "hatycon" [] [Plain con] -hTypeToXML (TyVar var) = Element "hatyvar" [] [Plain var] +hTypeToXML (TyCon con) = Element "hatycon" [] [Plain (unpackPS con)] +hTypeToXML (TyVar var) = Element "hatyvar" [] [Plain (unpackPS var)] hunk ./gendoc/XMLwrite.hs 125 - dTX (Words ws:ds) = (concatMap (\x -> [Plain x,WhiteSpace]) ws)++dTX ds - dTX (RefArg var fol:ds) = Element "emphasis" [] [Plain var]: - (if nullPS fol then id else (Plain fol:)) - (WhiteSpace:dTX ds) - dTX (RefSym _ var fol:ds) = Element "emphasis" [] [Plain var]: - (if nullPS fol then id else (Plain fol:)) - (WhiteSpace:dTX ds) - dTX (RefTyp _ var fol:ds) = Element "emphasis" [] [Plain var]: - (if nullPS fol then id else (Plain fol:)) - (WhiteSpace:dTX ds) - dTX (RefVariant var fol:ds) = Element "emphasis" [] [Plain var]: - (if nullPS fol then id else (Plain fol:)) - (WhiteSpace:dTX ds) - dTX (Verb str fol:ds) = Element "programlisting" [] [Plain str]: - (if nullPS fol then id else (Plain fol:)) - (WhiteSpace:dTX ds) + dTX (Words ws:ds) = + (concatMap (\x -> [Plain (unpackPS x),WhiteSpace]) ws)++dTX ds + dTX (RefArg var fol:ds) = Element "emphasis" [] [Plain (unpackPS var)]: + (if nullPS fol then id else (Plain (unpackPS fol):)) (WhiteSpace:dTX ds) + dTX (RefSym _ var fol:ds) = Element "emphasis" [] [Plain (unpackPS var)]: + (if nullPS fol then id else (Plain (unpackPS fol):)) (WhiteSpace:dTX ds) + dTX (RefTyp _ var fol:ds) = Element "emphasis" [] [Plain (unpackPS var)]: + (if nullPS fol then id else (Plain (unpackPS fol):)) (WhiteSpace:dTX ds) + dTX (RefVariant var fol:ds) = Element "emphasis" [] [Plain (unpackPS var)]: + (if nullPS fol then id else (Plain (unpackPS fol):)) (WhiteSpace:dTX ds) + dTX (Verb str fol:ds) = Element "literallayout" [] [Plain (unpackPS str)]: + (if nullPS fol then id else (Plain (unpackPS fol):)) (WhiteSpace:dTX ds) hunk ./gendoc/XMLwrite.hs 144 - Element "refname" [] [Plain mName], + Element "refname" [] [Plain (unpackPS mName)], hunk ./gendoc/XMLwrite.hs 149 - Attribute "frame" (packString "none"), - Attribute "colsep" (packString "0"), - Attribute "rowsep" (packString "0")] [ + Attribute "frame" "none", + Attribute "colsep" "0", + Attribute "rowsep" "0"] [ hunk ./gendoc/XMLwrite.hs 153 - Attribute "align" (packString "left"), - Attribute "cols" (packString "1")] [ + Attribute "align" "left", + Attribute "cols" "1"] [ hunk ./gendoc/XMLwrite.hs 156 - map (makeSynopsis ctxt) cons++ - map (makeSynopsis ctxt) const++ - map (makeSynopsis ctxt) func++ - map (makeSynopsis ctxt) meth++ - map (makeSynopsis ctxt) sign + map (makeSynopsis mName ctxt) cons++ + map (makeSynopsis mName ctxt) const++ + map (makeSynopsis mName ctxt) func++ + map (makeSynopsis mName ctxt) meth++ + map (makeSynopsis mName ctxt) sign hunk ./gendoc/XMLwrite.hs 167 - ++makeSect "Constructors" (map makeSymDescr cons) - ++makeSect "Methods" (map makeSymDescr meth) - ++makeSect "Functions" (map makeSymDescr func) - ++makeSect "Constants" (map makeSymDescr const) - ++makeSect "Signals" (map makeSymDescr sign) + ++makeSect "Constructors" (map (makeSymDescr mName ctxt) cons) + ++makeSect "Methods" (map (makeSymDescr mName ctxt) meth) + ++makeSect "Functions" (map (makeSymDescr mName ctxt) func) + ++makeSect "Constants" (map (makeSymDescr mName ctxt) const) + ++makeSect "Signals" (map (makeSymDescr mName ctxt) sign) hunk ./gendoc/XMLwrite.hs 194 - Element "title" [] [Plain (packString name)]:docu + Element "title" [] [Plain name]:docu hunk ./gendoc/XMLwrite.hs 197 -makeSynopsis :: FiniteMap TyVar TyCon -> (DaVar,SymInfo) -> XML -makeSynopsis contexts (var, SymInfo { symType=Just ty }) = +makeSynopsis :: Module -> FiniteMap TyVar TyCon -> (DaVar,SymInfo) -> XML +makeSynopsis mName contexts (var, SymInfo { symType=Just ty }) = hunk ./gendoc/XMLwrite.hs 201 - Element "programlisting" [] [ - Plain (var `appendPS` - packString (":: "++showContext ctxt++show ty)) + Element "literallayout" [ + Attribute "class" "monospaced"] [ + Element "link" [ + Attribute "linkend" (unpackPS mName++"."++unpackPS var) + ] [ + Plain (unpackPS var)], + Plain (":: "++showContext ctxt++show ty) hunk ./gendoc/XMLwrite.hs 217 -makeSynopsis contexts (var, _) = +makeSynopsis mName contexts (var, _) = hunk ./gendoc/XMLwrite.hs 220 - Element "programlisting" [] [ - Plain (var `appendPS` packString " <no type information>") + Element "literallayout" [] [ + Plain (unpackPS var++" ") hunk ./gendoc/XMLwrite.hs 228 -makeSymDescr :: (DaVar, SymInfo) -> XML -makeSymDescr (var, SymInfo { symKind=k, symDocu=doc, - symType=Just ty, symArgs=args }) = - Element "refsect2" [] ( - Element "title" [] [Plain var]: - docuToXML doc +makeSymDescr :: Module -> FiniteMap TyVar TyCon -> (DaVar, SymInfo) -> XML +makeSymDescr mName classMap (var, SymInfo { symKind=k, symDocu=doc, + symType=Just ty, symArgs=args }) = + Element "refsect2" [Attribute "id" (unpackPS mName++"."++unpackPS var)] ( + Element "title" [] [Plain (unpackPS var)]: + Element "informaltable" [ + Attribute "frame" "none", + Attribute "colsep" "0", + Attribute "rowsep" "0" + ] ( + Element "colspec" [] []: + replicate noOfCols + (Element "colspec" [Attribute "colwidth" "100pt"] [])++[ + Element "tgroup" [ + Attribute "align" "center", + Attribute "cols" (show noOfCols) + ] [ + Element "tbody" [ + Attribute "valign" "middle" + ] ( + Element "row" [] ( + Element "entry" [ + Attribute "morerows" (show noOfRows) + ] [ + Plain (unpackPS var) + ]:typeToXML (\_ -> Nothing) ty (Just formatter) + ):map argsToXML (transpose args) + ) + ] + ]):docuToXML doc hunk ./gendoc/XMLwrite.hs 259 -makeSymDescr (var, _) = Element "refsect2" [] - [Plain (packString "no type info on symbol"), Plain var] + where + noOfRows = case args of + [] -> 0 + (equations:_) -> length equations + noOfCols = length (take 50 args) -- don't loop forever if no defn + formatter :: [XML] -> [XML] -> [XML] + formatter x1 x2@(Element "entry" _ _:_) = + Element "entry" [] (Plain "::":WhiteSpace:x1):x2 + formatter x1 x2 = [Element "entry" [] (Plain "::":WhiteSpace:x1), + Element "entry" [ + Attribute "morerows" (show noOfRows)] + (Plain "::":WhiteSpace:x2)] + argsToXML :: [HPat] -> XML + argsToXML args = Element "row" [] (map argToXML args) + argToXML :: HPat -> XML + argToXML hPat = Element "entry" [] [Plain (show hPat)] + +makeSymDescr mName _ (var, _) = Element "refsect2" [] + [Plain "no type info on symbol ", Plain (unpackPS var)] + +-- Combine several consecutive Plain elements. +-- +flatten :: [XML] -> [XML] +flatten (Plain t1: Plain t2: xs) = flatten (Plain (t1++t2):xs) +flatten (x:xs) = x:flatten xs +flatten [] = [] + +-- Convert a type into XML. Each element in the list corresponds to one +-- element in the type. +-- +typeToXML :: (Var -> Maybe String) -> HType -> + Maybe ([XML] -> [XML] -> [XML]) -> [XML] +typeToXML varInfo ty comb = flatten $ ttX 0 (fromMaybe plain comb) ty + where + plain :: [XML] -> [XML] -> [XML] + plain xs1 xs2 = xs1++WhiteSpace:Plain "->":WhiteSpace:xs2 + ttX :: Int -> ([XML] -> [XML] -> [XML]) -> HType -> [XML] + ttX 0 f (TyFun t1 t2) = f (ttX 1 plain t1) (ttX 0 f t2) + ttX n _ (TyApp t1 t2) | n<2 = ttX 0 plain t1++WhiteSpace:ttX 2 plain t2 + ttX _ _ (TyCon con) = case varInfo con of + Nothing -> [Plain (unpackPS con)] + Just refName -> + [Element "link" [Attribute "linkend" refName] [Plain (unpackPS con)]] + ttX _ _ (TyVar var) = case varInfo var of + Nothing -> [Plain (unpackPS var)] + Just refName -> + [Element "link" [Attribute "linkend" refName] [Plain (unpackPS var)]] + ttX _ _ (TyPar tys) = Plain "(": + intersperse (Plain ",") + (concatMap (ttX 0 plain) tys)++ + [Plain ")"] + ttX _ _ (TyLst t) = Plain "[": + ttX 0 plain t++ + [Plain "]"] + ttX _ _ t = Plain "(":ttX 0 plain t++[Plain ")"] + }