Menu
▾
▴
[Gtk2hs-commit] gtk2hs/tools/apiGen format-docs.xsl,1.3,1.4 ApiGen.hs,1.3,1.4 gen-all.sh,1.2,1.3 Template.chs,1.2,1.3
|
From: Duncan C. <dun...@us...> - 2005-01-10 17:23:16
|
Update of /cvsroot/gtk2hs/gtk2hs/tools/apiGen In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4629/tools/apiGen Modified Files: format-docs.xsl ApiGen.hs gen-all.sh Template.chs Log Message: Deal with more complicated formatting, definition lists, itemised lists, subsections, titled and untitled program listing examples. It now works for all modules in gtk 2.6 Index: Template.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/tools/apiGen/Template.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- Template.chs 7 Jan 2005 17:45:40 -0000 1.2 +++ Template.chs 10 Jan 2005 17:23:05 -0000 1.3 @@ -22,7 +22,7 @@ -- Stability : provisional -- Portability : non-portable (uses gtk+ C library) -- --- @DESCRIPTION@ @TODO@ +-- @DESCRIPTION@@TODO@ -- module @MODULE_NAME@ ( @DOCUMENTATION@ @@ -30,9 +30,9 @@ ) where import Monad (liftM) -import Foreign -import Foreign.C + +import System.Glib.FFI @IMPORTS@ -{#context lib="@CONTEXT_LIB@" prefix="@CONTEXT_PREFIX@" #} +{# context lib="@CONTEXT_LIB@" prefix="@CONTEXT_PREFIX@" #} @MODULE_BODY@ Index: format-docs.xsl =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/tools/apiGen/format-docs.xsl,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- format-docs.xsl 9 Jan 2005 23:45:11 -0000 1.3 +++ format-docs.xsl 10 Jan 2005 17:23:04 -0000 1.4 @@ -28,32 +28,66 @@ <arg><xsl:value-of select="."/></arg> </xsl:template> +<xsl:template match="para[not(example) and not(informalexample)]"> +<para><xsl:apply-templates/></para> +</xsl:template> + +<xsl:template match="para[informalexample]"> +<para><xsl:apply-templates select="node()[name()!='informalexample']"/></para> +<xsl:apply-templates select="informalexample"/> +</xsl:template> + +<xsl:template match="para[example]"> +<para><xsl:apply-templates select="node()[name()!='example']"/></para> +<xsl:apply-templates select="example"/> +</xsl:template> + +<xsl:template match="varlistentry"> +<definition> + <term><xsl:value-of select="term"/></term> + <xsl:apply-templates select="listitem/para/child::node()"/> +</definition> +</xsl:template> + +<xsl:template match="itemizedlist/listitem/para"> +<listitem><xsl:apply-templates/></listitem> +</xsl:template> + +<xsl:template match="section | refsect2"> +<section> + <title><xsl:value-of select="title"/></title> + <xsl:apply-templates select="para | programlisting | example"/> +</section> +</xsl:template> + +<xsl:template match="example"> +<example> + <title><xsl:value-of select="title"/></title> + <xsl:apply-templates select="para | programlisting"/> +</example> +</xsl:template> + +<xsl:template match="programlisting"> +<programlisting><xsl:value-of select="."/></programlisting> +</xsl:template> + +<xsl:template match="footnote"></xsl:template> + <xsl:template match="/"> <apidoc> <module> <name><xsl:value-of select="/book/refentry/refnamediv/refname"/></name> <summary><xsl:value-of select="/book/refentry/refnamediv/refpurpose"/></summary> <description> - <xsl:for-each select="/book/refentry/refsect1[title='Description']/para"> - <para><xsl:apply-templates/></para> + <xsl:for-each select="/book/refentry/refsect1[title='Description']"> + <xsl:apply-templates select="para | section | refsect2"/> </xsl:for-each> </description> - <extra-sections> - <xsl:for-each select="/book/refentry/refsect1[title='Description']/section"> - <section> - <title><xsl:value-of select="title"/></title> - <xsl:for-each select="para | programlisting"> - <xsl:if test="name()='para'"> - <para><xsl:apply-templates/></para> - </xsl:if> - <xsl:if test="name()='programlisting'"> - <xsl:copy-of select="."/> - </xsl:if> - </xsl:for-each> - </section> + <object-hierarchy> + <xsl:for-each select="/book/refentry/refsect1[title='Object Hierarchy']/synopsis"> + <xsl:copy-of select="text() | link"/> </xsl:for-each> - </extra-sections> - <object-hierarchy></object-hierarchy> + </object-hierarchy> </module> <xsl:for-each select="/book/refentry/refsect1[title='Details']/refsect2[contains(title,' ()')]"> <function> @@ -62,10 +96,7 @@ <xsl:value-of select="normalize-space(substring-after(para[starts-with(text(),'Since')], 'Since'))"/> </since> <doc> - <xsl:for-each select="para[not(starts-with(text(),'Since')) and normalize-space(text())!='']"> - <!--<xsl:copy-of select="."/>--> - <para><xsl:apply-templates/></para> - </xsl:for-each> + <xsl:apply-templates select="para[not(starts-with(text(),'Since')) and normalize-space(text())!='']"/> </doc> </function> </xsl:for-each> Index: gen-all.sh =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/tools/apiGen/gen-all.sh,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- gen-all.sh 7 Jan 2005 17:45:40 -0000 1.2 +++ gen-all.sh 10 Jan 2005 17:23:05 -0000 1.3 @@ -1,7 +1,7 @@ #!/bin/bash -DOCBOOKDIR=../apicoverage/tars/gtk+-2.4.13/docs/reference/gtk/xml -HEADDERS=/usr/include/gtk-2.0/gtk/*.h +DOCBOOKDIR=../apicoverage/tars/gtk+-2.6.1/docs/reference/gtk/xml +HEADDERS=../apicoverage/tars/image/usr/local/include/gtk-2.0/gtk/*.h mkdirhier doc api modules echo > modules/missing_docs @@ -14,7 +14,7 @@ DOCFILE=doc/$(basename ${HEADDER%.h}).xml echo Processing $HEADDER - ./gapi_pp.pl $HEADDER | ./gapi2xml.pl Gtk $APIFILE gtk+ >> /dev/null || exit + ./gapi_pp.pl $HEADDER | ./gapi2xml.pl Gtk $APIFILE gtk >> /dev/null || exit # ./gapi_format_xml $APIFILE.tmp $APIFILE || exit # rm $APIFILE.tmp Index: ApiGen.hs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/tools/apiGen/ApiGen.hs,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- ApiGen.hs 9 Jan 2005 23:45:11 -0000 1.3 +++ ApiGen.hs 10 Jan 2005 17:23:05 -0000 1.4 @@ -162,18 +162,18 @@ ------------------------------------------------------------------------------- data ApiDoc = ApiDoc { - apidoc_name :: String, - apidoc_summary :: String, - apidoc_description :: [DocPara], - apidoc_extrasections :: [DocSection], - apidoc_functions :: [FuncDoc] + apidoc_name :: String, -- these docs apply to this object + apidoc_summary :: String, -- a one line summary + apidoc_description :: [DocPara], -- the main description + apidoc_sections :: [DocSection], -- any additional titled subsections + apidoc_functions :: [FuncDoc] -- documentation for each function } noApiDoc = ApiDoc { apidoc_name = "", apidoc_summary = "", apidoc_description = [], - apidoc_extrasections = [], + apidoc_sections = [], apidoc_functions = [] } @@ -188,8 +188,12 @@ funcdoc_since :: Maybe String -- which version of the api the } -- function is avaliable from, eg "2.4" -data DocPara = TextPara [DocParaSpan] - | ProgramListing String +data DocPara = + DocParaText [DocParaSpan] -- an ordinary word-wrapped paragraph + | DocParaProgram String -- a verbatum section + | DocParaExample String String -- a verbatum section with a title + | DocParaDefItem String [DocParaSpan] -- a definition list item + | DocParaListItem [DocParaSpan] -- a itemisted list item data DocParaSpan = DocText String -- just simple text | DocFuncXRef String -- cross reference to a function name @@ -210,14 +214,18 @@ (Xml.CElem (Xml.Elem "module" [] [Xml.CElem (Xml.Elem "name" [] name) ,Xml.CElem (Xml.Elem "summary" [] summary) - ,Xml.CElem (Xml.Elem "description" [] paras) - ,Xml.CElem (Xml.Elem "extra-sections" [] sections) + ,Xml.CElem (Xml.Elem "description" [] parasAndSections) ,Xml.CElem (Xml.Elem "object-hierarchy" [] _)] - )) = ApiDoc { + )) = + let (paras, sections) = span (\elem -> + case elem of + Xml.CElem (Xml.Elem "section" _ _) -> False + _ -> True) parasAndSections + in ApiDoc { apidoc_name = Xml.verbatim name, apidoc_summary = Xml.verbatim summary, - apidoc_description = map extractDocPara paras, - apidoc_extrasections = map extractDocSection sections, + apidoc_description = concatMap extractDocPara paras, + apidoc_sections = map extractDocSection sections, apidoc_functions = undefined } @@ -228,7 +236,7 @@ :paras))) = DocSection { section_title = title, - section_paras = map extractDocPara paras + section_paras = concatMap extractDocPara paras } extractDocSection other = error $ "extractDocSection: " ++ Xml.verbatim other @@ -244,16 +252,51 @@ [Xml.CString _ since] -> Just since in FuncDoc { funcdoc_name = name, - funcdoc_paragraphs = map extractDocPara paras, + funcdoc_paragraphs = concatMap extractDocPara paras, funcdoc_since = since } -extractDocPara :: Xml.Content -> DocPara +extractDocPara :: Xml.Content -> [DocPara] extractDocPara (Xml.CElem elem@(Xml.Elem "para" [] _)) = case Xml.xmlUnEscape Xml.stdXmlEscaper elem of - (Xml.Elem _ [] spans) -> TextPara (map extractDocParaSpan spans) -extractDocPara (Xml.CElem (Xml.Elem "programlisting" _ [Xml.CString _ listing])) = - ProgramListing listing + (Xml.Elem _ [] spans) -> extractDocPara' spans +extractDocPara (Xml.CElem (Xml.Elem "programlisting" _ content)) = + let listing = concat [ str | (Xml.CString _ str) <- content ] in + [DocParaProgram listing] +extractDocPara (Xml.CElem (Xml.Elem "example" _ + [Xml.CElem (Xml.Elem "title" [] [Xml.CString _ title]) + ,(Xml.CElem (Xml.Elem "programlisting" _ content))])) = + let listing = concat [ str | (Xml.CString _ str) <- content ] in + [DocParaExample title listing] +{-extractDocPara (Xml.CElem (Xml.Elem "example" _ + [Xml.CElem (Xml.Elem "title" [] [Xml.CString _ title]) + ,(Xml.CElem (Xml.Elem "programlisting" _ other))])) = error $ "extractDocPara: example1:\n" ++ Prelude.unlines (map ((++ "\n\n\nFOOBAR\n\n\n") . Xml.verbatim) other) ++ "\n len = " ++ show (length other) +extractDocPara (Xml.CElem (Xml.Elem "example" _ other)) = error $ "extractDocPara: example2:\n" ++ Xml.verbatim other ++ "\n len = " ++ show (length other)-} +extractDocPara other = error $ "extractDocPara: " ++ Xml.verbatim other + +extractDocPara' :: [Xml.Content] -> [DocPara] +extractDocPara' = reconstructParas [] . map extractDocParaOrSpan + where reconstructParas :: [DocParaSpan] -> [Either DocParaSpan DocPara] -> [DocPara] + reconstructParas [] [] = [] + reconstructParas spans [] = [DocParaText (reverse spans)] + reconstructParas spans (Left span:rest) = reconstructParas (span:spans) rest + reconstructParas [] (Right para:rest) = para : reconstructParas [] rest + reconstructParas spans (Right para:rest) = DocParaText (reverse spans) + : para : reconstructParas [] rest + +extractDocParaOrSpan :: Xml.Content -> Either DocParaSpan DocPara +extractDocParaOrSpan (Xml.CElem (Xml.Elem "listitem" [] content)) = + Right $ DocParaListItem (map extractDocParaSpan content) +extractDocParaOrSpan (Xml.CElem (Xml.Elem "definition" [] + (Xml.CElem (Xml.Elem "term" [] [Xml.CString _ term]) + :content))) = + Right $ DocParaDefItem term (map extractDocParaSpan content) +extractDocParaOrSpan (Xml.CElem (Xml.Elem "programlisting" _ content)) = + let listing = concat [ str | (Xml.CString _ str) <- content ] in + Right $ DocParaProgram listing +extractDocParaOrSpan content@(Xml.CElem _ ) = Left $ extractDocParaSpan content +extractDocParaOrSpan content@(Xml.CString _ _) = Left $ extractDocParaSpan content +extractDocParaOrSpan other = error $ "extractDocParaOrSpan: " ++ Xml.verbatim other extractDocParaSpan :: Xml.Content -> DocParaSpan extractDocParaSpan (Xml.CString _ text) = DocText text @@ -266,6 +309,7 @@ "emphasis" -> DocEmphasis text "literal" -> DocLiteral text "arg" -> DocArg text + other -> error $ "extractDocParaSpan: other tag " ++ tag extractDocParaSpan other = error $ "extractDocParaSpan: " ++ Xml.verbatim other ------------------------------------------------------------------------------- @@ -279,9 +323,9 @@ else comment.ss "* Description".nl. comment.nl. comment.ss "| ".haddocFormatParas (apidoc_description apidoc).nl). - (if null (apidoc_extrasections apidoc) + (if null (apidoc_sections apidoc) then id - else nl.comment.haddocFormatSections (apidoc_extrasections apidoc).nl.comment) + else nl.comment.haddocFormatSections (apidoc_sections apidoc).nl.comment) addVersionParagraphs :: NameSpace -> ApiDoc -> ApiDoc addVersionParagraphs namespace apiDoc = @@ -296,7 +340,7 @@ funcdoc_paragraphs = funcdoc_paragraphs funcdoc ++ let line = "Available since " ++ namespace_name namespace ++ " version " ++ fromJust (funcdoc_since funcdoc) - in [TextPara [DocText line]] + in [DocParaText [DocText line]] } else funcdoc | funcdoc <- funcdocs ] @@ -307,7 +351,7 @@ Just since -> let line = "Module available since " ++ namespace_name namespace ++ " version " ++ since - in [TextPara [DocText line]] + in [DocParaText [DocText line]] -- figure out if the whole module appeared in some version of gtk later -- than the original version @@ -331,19 +375,33 @@ . map haddocFormatPara haddocFormatPara :: DocPara -> ShowS -haddocFormatPara (TextPara spans) = - sepBy' "\n-- " - . map (sepBy " ") - . wrapText 77 - . words - . concatMap haddocFormatSpan - $ spans -haddocFormatPara (ProgramListing prog) = +haddocFormatPara (DocParaText spans) = haddocFormatSpans spans +haddocFormatPara (DocParaProgram prog) = ((ss "* FIXME: port the follwing code example from C to Haskell or remove it".nl. comment).) . sepBy "\n-- > " . List.lines $ prog +haddocFormatPara (DocParaExample title prog) = + ((ss "* ". ss title.nl. + comment).) + . sepBy "\n-- > " + . List.lines + $ prog +haddocFormatPara (DocParaDefItem term spans) = + sc '['. ss term. sc ']'. + haddocFormatSpans spans +haddocFormatPara (DocParaListItem spans) = + ss "* ". + haddocFormatSpans spans + +haddocFormatSpans :: [DocParaSpan] -> ShowS +haddocFormatSpans = + sepBy' "\n-- " + . map (sepBy " ") + . wrapText 77 + . words + . concatMap haddocFormatSpan haddocFormatSpan :: DocParaSpan -> String haddocFormatSpan (DocText text) = escapeHaddockSpecialChars text @@ -378,7 +436,7 @@ -- wraps a list of words to lines of words wrapText :: Int -> [String] -> [[String]] -wrapText width = wrap 0 [] +wrapText width = wrap 3 [] where wrap :: Int -> [String] -> [String] -> [[String]] wrap col line (word:words) | col + length word + 1 > width = reverse line : wrap 0 [] (word:words) @@ -394,7 +452,7 @@ formattedDoc. ss functionName. ss " :: ". functionType. nl. ss functionName. sc ' '. sepBy " " paramNames. ss " =". - indent 1. body. nl + indent 1. body where functionName = lowerCaseFirstChar (method_name method) (classConstraints', paramTypes', paramMarshalers) = @@ -419,6 +477,12 @@ Just doc -> ss "-- | ". haddocFormatParas (funcdoc_paragraphs doc). nl. comment. nl +genModuleBody :: Object -> ApiDoc -> ShowS +genModuleBody object apiDoc = + doVersionIfDefs (sepBy' "\n\n") $ + genConstructors object (apidoc_functions apiDoc) + ++ genMethods object (apidoc_functions apiDoc) + genMethods :: Object -> [FuncDoc] -> [(ShowS, Maybe FuncDoc)] genMethods object apiDoc = [ (genFunction object method doc, doc) @@ -478,13 +542,13 @@ genExports object docs = nl. comment.ss "* Constructors".nl. - doVersionIfDefs + doVersionIfDefs lines [ (ss " ". ss (lowerCaseFirstChar (method_name constructor)). sc ',', doc) | (constructor, doc) <- constructors object docs]. nl. nl. comment.ss "* Methods".nl. - doVersionIfDefs + doVersionIfDefs lines [ (ss " ". ss (lowerCaseFirstChar (method_name method)). sc ',', doc) | (method, doc) <- methods object docs] @@ -504,8 +568,8 @@ ss "TODO: the following varargs functions were not bound\n". lines (map (ss "-- * ".) varargsFunctions) -doVersionIfDefs :: [(ShowS, Maybe FuncDoc)] -> ShowS -doVersionIfDefs = +doVersionIfDefs :: ([ShowS] -> ShowS) -> [(ShowS, Maybe FuncDoc)] -> ShowS +doVersionIfDefs lines = lines . map (\group -> sinceVersion (snd (head group)) (lines (map fst group))) @@ -700,8 +764,7 @@ "IMPORTS" -> ss "-- CHECKME: extra imports may be required\n" "CONTEXT_LIB" -> ss (if null lib then namespace_library namespace else lib) "CONTEXT_PREFIX" -> ss (if null prefix then namespace_library namespace else prefix) - "MODULE_BODY" -> doVersionIfDefs (genConstructors object (apidoc_functions apiDoc') - ++ genMethods object (apidoc_functions apiDoc')) + "MODULE_BODY" -> genModuleBody object apiDoc' _ -> ss "" ) "") [ (namespace, object) | namespace <- api |
