Update the manual to odf 1.1

manual/buildmanual.py

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2006 Søren Roug, European Environment Agency
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+#
+# Contributor(s):
+#
+
+from odf.opendocument import OpenDocumentText
+from odf import grammar
+from odf.namespaces import *
+from odf import style, text
+
+
+def listofelements(p, elements,anytext, nonetext):
+    if elements is None:
+        p.addText(anytext)
+    elif elements is () or elements is []:
+        p.addText(nonetext)
+    else:
+        elclasses = [ makeclass(e) for e in elements]
+        elclasses.sort()
+        for m in elclasses:
+#           m = makeclass(e)
+            bm = text.BookmarkRef(referenceformat="text",refname=m)
+            bm.addText(m)
+            p.addElement(bm)
+            if m != elclasses[-1]:
+                p.addText(", ")
+    p.addText(".")
+
+# Invert the children dictionary to construct parents
+parents = {}
+
+ns=''
+for parent, children in grammar.allowed_children.items():
+    if children:
+        for child in children:
+            if not parents.has_key(child):
+                parents[child] = []
+            if not parent in parents[child]:
+                parents[child].append(parent)
+
+
+doc=OpenDocumentText()
+textdoc = doc.text
+
+def makeclass(t):
+    return "%s.%s" % ( nsdict[t[0]], t[1].title().replace('-',''))
+
+# Styles
+h1style = style.Style(name="Heading 1",family="paragraph")
+h1style.addElement(style.TextProperties(attributes={'fontsize':"24pt", 'fontweight':"bold"}))
+doc.styles.addElement(h1style)
+h2style = style.Style(name="Heading 2",family="paragraph")
+h2style.addElement(style.TextProperties(attributes={'fontsize':"16pt", 'fontweight':"bold", 'fontstyle':"italic"}))
+doc.styles.addElement(h2style)
+h3style = style.Style(name="Heading 3",family="paragraph")
+h3style.addElement(style.TextProperties(attributes={'fontsize':"14pt", 'fontweight':"bold"}))
+doc.styles.addElement(h3style)
+
+#boldstyle = style.Style(name="Bold",family="text")
+#boldstyle.addElement(style.TextProperties(attributes={'fontweight':"bold"}))
+#textdoc.automaticstyles.addElement(boldstyle)
+
+attrliststyle = style.Style(name="Attribute List",family="text")
+attrliststyle.addElement(style.TextProperties(fontstyle="italic"))
+doc.styles.addElement(attrliststyle)
+
+elmliststyle = style.Style(name="Element List",family="text")
+elmliststyle.addElement(style.TextProperties(fontstyle="italic"))
+doc.styles.addElement(elmliststyle)
+
+# Text
+h = text.H(outlinelevel=1, stylename=h1style, text="API for odfpy")
+textdoc.addElement(h)
+section = text.Section(name="modules")
+textdoc.addElement(section)
+
+def elmcmp(e1, e2):
+    n1 = nsdict[e1[0]]
+    n2 = nsdict[e2[0]]
+    if cmp(n1,n2) != 0: return cmp(n1,n2)
+    return cmp(e1[1], e2[1])
+
+childkeys = grammar.allowed_children.keys()
+childkeys.sort(elmcmp)
+ns=''
+for element in childkeys:
+    children = grammar.allowed_children[element]
+    if ns != nsdict[element[0]]:
+        ns = nsdict[element[0]]
+        section.addElement(text.H(outlinelevel=2, stylename=h2style,text="%s module" % ns))
+    classname = makeclass(element)
+    h3 = text.H(outlinelevel=3, stylename=h3style)
+    h3.addElement(text.BookmarkStart(name=classname))
+    h3.addText(classname)
+    h3.addElement(text.BookmarkEnd(name=classname))
+    section.addElement(h3)
+
+    # Required attributes
+    p = text.P(text="Requires the following attributes: ")
+    required_attributes = grammar.required_attributes.get(element)
+    if required_attributes is None:
+        info = "No attribute is required"
+    elif required_attributes is ():
+        info = "No attribute is required"
+    else:
+        required_args = [ a[1].lower().replace('-','') for a in required_attributes]
+        required_args.sort()
+        info = ', '.join(required_args)
+    p.addElement(text.Span(stylename=attrliststyle, text=info+"."))
+    section.addElement(p)
+
+    # Allowed attributes
+    p = text.P(text="Allows the following attributes: ")
+    allowed_attrs = grammar.allowed_attributes.get(element)
+    if allowed_attrs is None:
+        info = "No attribute is allowed"
+    elif allowed_attrs is ():
+        info = "No attribute is allowed"
+    else:
+        allowed_args = [ a[1].lower().replace('-','') for a in allowed_attrs]
+        allowed_args.sort()
+        info = ', '.join(allowed_args)
+    p.addElement(text.Span(stylename=attrliststyle, text=info))
+    p.addText(".")
+    section.addElement(p)
+
+    #PARENTS
+    p = text.P(text="These elements contain %s: " % classname)
+    i = text.Span(stylename=elmliststyle)
+    p.addElement(i)
+    listofelements(i, parents.get(element),"This is a toplevel element","This is a toplevel element")
+    section.addElement(p)
+
+    #CHILDREN
+    p = text.P(text="The following elements occur in %s: " % classname)
+    i = text.Span(stylename=elmliststyle)
+    p.addElement(i)
+    listofelements(i, children,"Any element is allowed","No element is allowed")
+    section.addElement(p)
+
+#boldpart = text.Span(stylename="Bold",text="This part is bold. ")
+#p.addElement(boldpart)
+#p.addText("This is after bold.")
+
+#   print d.contentxml()
+doc.save("manual.odt")
+

manual/htmlmanual.py

@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2009 Søren Roug, European Environment Agency
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+#
+# Contributor(s):
+#
+
+from odf import grammar
+from odf.namespaces import *
+from odf import style, text
+
+textfd = None
+
+def header(module):
+    global textfd
+    print >>textfd, """<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-gb">
+  <head>
+    <title>ODFPY</title>
+    <link rel="stylesheet" type="text/css" href="../styles/screen.css" media="screen"/>
+    <link rel="stylesheet" type="text/css" href="../styles/print.css" media="print"/>
+    <script type="text/javascript" src="../styles/mark_special_links.js"></script>
+  </head>
+  <body>
+    <div id="container">
+      <div id="pagehead"> ODFPY - a Python library to manipulate ODF files </div>
+      <div class="breadcrumbtrail">
+        <div class="breadcrumbhead">You are here:</div>
+        <div class="breadcrumbitem">
+          <a href="/">ODFPY</a>
+        </div>
+        <div class="breadcrumbitem">
+          <a href="/manual">Manual</a>
+        </div>
+	<div class="breadcrumbitemlast">%s module</div>
+        <div class="breadcrumbtail"/>
+      </div>
+      <div id="leftcolumn">
+        <ul>
+          <li>
+            <a href="http://forge.osor.eu/projects/odfpy/">OSOR Project page</a>
+          </li>
+          <li>
+            <a href="http://pypi.python.org/pypi/odfpy/">Python package index</a>
+          </li>
+          <li>
+            <a href="http://forge.osor.eu/frs/?group_id=33">Download</a>
+          </li>
+          <li>
+            <a href="../manual">Manual</a>
+          </li>
+          <li>
+            <a href="../examples.html">Examples</a>
+          </li>
+        </ul>
+      </div>
+      <div id="content">
+""" % module
+
+def footer():
+    global textfd
+    print >>textfd, """
+    </div>
+      <!-- content -->
+    </div>
+    <!-- container -->
+    <div id="pagefoot"> s&#xF8;n mar 15 15:15:53 CET 2009 </div>
+  </body>
+</html>"""
+
+def elmcmp(e1, e2):
+    n1 = nsdict[e1[0]]
+    n2 = nsdict[e2[0]]
+    if cmp(n1,n2) != 0: return cmp(n1,n2)
+    return cmp(e1[1], e2[1])
+
+
+def listofelements(elements, anytext, nonetext):
+    global textfd
+    if elements is None:
+        x = anytext
+    elif elements is () or elements is []:
+        x = nonetext
+    else:
+        elclasses = [ makehref(e) for e in elements]
+        elclasses.sort()
+        x = ", ".join(elclasses)
+    print >>textfd, """<span class="elements">%s</span>.""" % x
+
+# Invert the children dictionary to construct parents
+parents = {}
+
+ns=''
+for parent, children in grammar.allowed_children.items():
+    if children:
+        for child in children:
+            if not parents.has_key(child):
+                parents[child] = []
+            if not parent in parents[child]:
+                parents[child].append(parent)
+
+
+def makeid(t):
+    return t[1].title().replace('-','')
+
+def makehref(t):
+
+    return """<a href="%s.html#%s">%s.%s</a>""" % ( nsdict[t[0]], t[1].title().replace('-',''),
+          nsdict[t[0]], t[1].title().replace('-',''))
+
+def makeclass(t):
+    return "%s.%s" % ( nsdict[t[0]], t[1].title().replace('-',''))
+
+
+
+childkeys = grammar.allowed_children.keys()
+childkeys.sort(elmcmp)
+ns = ''
+
+
+for element in childkeys:
+    children = grammar.allowed_children[element]
+    if ns != nsdict[element[0]]:
+        if ns != '':
+            footer()
+            textfd.close()
+        ns = nsdict[element[0]]
+        textfd = open("%s.html" % ns, "w")
+        header(ns)
+        print >>textfd, "<h1>%s module</h1>" % ns
+    classname = makeclass(element)
+    print >>textfd, """<h2 id="%s">%s</h2>""" % ( makeid(element), classname)
+
+    # Required attributes
+    print >>textfd, "<p>Requires the following attributes:",
+    required_attributes = grammar.required_attributes.get(element)
+    if required_attributes is None or required_attributes is ():
+        info = "No attribute is required"
+    else:
+        required_args = [ a[1].lower().replace('-','') for a in required_attributes]
+        required_args.sort()
+        info = ', '.join(required_args)
+    print >>textfd, """<span class="attributes">%s.</span></p>""" % info
+
+    # Allowed attributes
+    print >>textfd, "<p>Allows the following attributes:",
+    allowed_attrs = grammar.allowed_attributes.get(element)
+    if allowed_attrs is None or allowed_attrs is ():
+        info = "No attribute is allowed"
+    else:
+        allowed_args = [ a[1].lower().replace('-','') for a in allowed_attrs]
+        allowed_args.sort()
+        info = ', '.join(allowed_args)
+    print >>textfd, """<span class="attributes">%s.</span></p>""" % info
+
+    #PARENTS
+    print >>textfd, "<p>These elements contain %s:" % classname,
+    listofelements(parents.get(element),"This is a toplevel element","This is a toplevel element")
+    print >>textfd, "</p>"
+
+    #CHILDREN
+    print >>textfd, "<p>The following elements occur in %s: " % classname,
+    listofelements(children,"Any element is allowed","No element is allowed")
+    print >>textfd, "</p>"

odf/grammar.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2006-2008 Søren Roug, European Environment Agency
+# Copyright (C) 2006-2009 Søren Roug, European Environment Agency
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public

odf/namespaces.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2006-2007 Søren Roug, European Environment Agency
+# Copyright (C) 2006-2009 Søren Roug, European Environment Agency
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public

odf/opendocument.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2006-2008 Søren Roug, European Environment Agency
+# Copyright (C) 2006-2009 Søren Roug, European Environment Agency
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -300,6 +300,37 @@ def addPicture(self, filename, mediatype=None, content=None):
             self.Pictures[manifestfn] = (IS_IMAGE, content, mediatype)
         return manifestfn
 
+    def addPictureFromFile(self, filename, mediatype=None):
+        """ Add a picture
+            It uses the same convention as OOo, in that it saves the picture in
+            the zipfile in the subdirectory 'Pictures'.
+            If mediatype is not given, it will be guessed from the filename
+            extension.
+        """
+        if mediatype is None:
+            mediatype, encoding = mimetypes.guess_type(filename)
+        if mediatype is None:
+            mediatype = ''
+            try: ext = filename[filename.rindex('.'):]
+            except ValueError: ext=''
+        else:
+            ext = mimetypes.guess_extension(mediatype)
+        manifestfn = "Pictures/%0.0f%s" % ((time.time()*10000000000), ext)
+        self.Pictures[manifestfn] = (IS_FILENAME, filename, mediatype)
+        return manifestfn
+
+    def addPictureFromString(self, content, mediatype):
+        """ Add a picture
+            It uses the same convention as OOo, in that it saves the picture in
+            the zipfile in the subdirectory 'Pictures'. The content variable
+            is a string that contains the binary image data. The mediatype
+            indicates the image format.
+        """
+        ext = mimetypes.guess_extension(mediatype)
+        manifestfn = "Pictures/%0.0f%s" % ((time.time()*10000000000), ext)
+        self.Pictures[manifestfn] = (IS_IMAGE, content, mediatype)
+        return manifestfn
+
     def addThumbnail(self, filecontent=None):
         """ Add a fixed thumbnail
             The thumbnail in the library is big, so this is pretty useless.