common/mangle-tmpl.py

   1 # -*- Mode: Python -*-
   2 # vi:si:et:sw=4:sts=4:ts=4
   3
   4 """
   5 use the output from gst-xmlinspect.py to mangle tmpl/*.sgml and
   6 insert/overwrite Short Description and Long Description
   7 """
   8
   9 # FIXME: right now it uses pygst and scans on its own;
  10 # we really should use inspect/*.xml instead since the result of
  11 # gst-xmlinspect.py is commited by the docs maintainer, who can be
  12 # expected to have pygst, but this step should be done for every docs build,
  13 # so no pygst allowed
  14
  15 # read in inspect/*.xml
  16 # for every tmpl/element-(name).xml: mangle with details from element
  17
  18 import glob
  19 import re
  20 import sys
  21 import os
  22
  23 class Tmpl:
  24     def __init__(self, filename):
  25         self.filename = filename
  26         self._sectionids = []
  27         self._sections = {}
  28
  29     def read(self):
  30         """
  31         Read and parse the sections from the given file.
  32         """
  33         lines = open(self.filename).readlines()
  34         matcher = re.compile("<!-- ##### SECTION (\S+) ##### -->\n")
  35         id = None
  36
  37         for line in lines:
  38             match = matcher.search(line)
  39             if match:
  40                 id = match.expand("\\1")
  41                 self._sectionids.append(id)
  42                 self._sections[id] = []
  43             else:
  44                 if not id:
  45                     sys.stderr.write(
  46                         "WARNING: line before a SECTION header: %s" % line)
  47                 else:
  48                     self._sections[id].append(line)
  49
  50     def get_section(self, id):
  51         """
  52         Get the content from the given section.
  53         """
  54         return self._sections[id]
  55
  56     def set_section(self, id, content):
  57         """
  58         Replace the given section id with the given content.
  59         """
  60         self._sections[id] = content
  61
  62     def output(self):
  63         """
  64         Return the output of the current template in the tmpl/*.sgml format.
  65         """
  66         lines = []
  67         for id in self._sectionids:
  68             lines.append("<!-- ##### SECTION %s ##### -->\n" % id)
  69             for line in self._sections[id]:
  70                 lines.append(line)
  71
  72         return "".join(lines)
  73
  74     def write(self, backup=False):
  75         """
  76         Write out the template file again, backing up the previous one.
  77         """
  78         if backup:
  79             target = self.filename + ".mangle.bak"
  80             os.rename(self.filename, target)
  81
  82         handle = open(self.filename, "w")
  83         handle.write(self.output())
  84         handle.close()
  85
  86 from xml.dom.ext.reader import Sax2
  87 from xml.dom.NodeFilter import NodeFilter
  88
  89 def get_elements(file):
  90     elements = {}
  91     handle = open(file)
  92     reader = Sax2.Reader()
  93     doc = reader.fromStream(handle)
  94     handle.close()
  95
  96     walker = doc.createTreeWalker(doc.documentElement,
  97         NodeFilter.SHOW_ELEMENT, None, 0)
  98     while walker.currentNode and walker.currentNode.tagName != 'elements':
  99         walker.nextNode()
 100
 101     # we're at elements now
 102     el = walker.firstChild()
 103     while walker.currentNode:
 104         element = walker.firstChild()
 105         # loop over children of <element>
 106         name = None
 107         description = None
 108         while walker.currentNode:
 109             if walker.currentNode.tagName == 'name':
 110                 name = walker.currentNode.firstChild.data.encode('UTF-8')
 111             if walker.currentNode.tagName == 'description':
 112                 description = walker.currentNode.firstChild.data.encode('UTF-8')
 113             if not walker.nextSibling(): break
 114         # back up to <element>
 115         walker.parentNode()
 116         elements[name] = {'description': description}
 117
 118         if not walker.nextSibling(): break
 119
 120     return elements
 121
 122
 123 def main():
 124     if not len(sys.argv) == 3:
 125         sys.stderr.write('Please specify the inspect/ dir and the tmpl/ dir')
 126         sys.exit(1)
 127
 128     inspectdir = sys.argv[1]
 129     tmpldir = sys.argv[2]
 130
 131     # parse all .xml files; build map of element name -> short desc
 132     #for file in glob.glob("inspect/plugin-*.xml"):
 133     elements = {}
 134     for file in glob.glob("%s/plugin-*.xml" % inspectdir):
 135         elements.update(get_elements(file))
 136
 137     for file in glob.glob("%s/element-*.sgml" % tmpldir):
 138         base = os.path.basename(file)
 139         element = base[len("element-"):-len(".sgml")]
 140         tmpl = Tmpl(file)
 141         tmpl.read()
 142         if element in elements.keys():
 143             description = elements[element]['description']
 144             tmpl.set_section("Short_Description", "%s\n\n" % description)
 145
 146         # put in an include if not yet there
 147         line = '<include xmlns="http://www.w3.org/2003/XInclude" href="' + \
 148             'element-' + element + '-details.xml" />\n'
 149         section = tmpl.get_section("Long_Description")
 150         if not section[0]  == line:
 151             section.insert(0, line)
 152         tmpl.set_section("Long_Description", section)
 153         tmpl.write()
 154
 155 main()