path: root/source/docbook.py

import sys, string
import globals, node

class FilePathSorter:

    def __init__ (self, filepaths):
        self.filepaths = filepaths
        self.root = node.Root()

    def buildPaths (self):
        for filepath in self.filepaths:
            # NOTE: we assume that none of the file names begin with '/'.
            hier = filepath.split('/')
            curnode = self.root
            for _dir in hier[:-1]:
                temp = curnode.firstChildByName(_dir)
                if temp == None:
                    # new directory node.
                    curnode = curnode.appendElement(_dir)
                else:
                    # directory node already exists.
                    curnode = temp

            # append file as a content node.
            curnode.appendContent(hier[-1])
            
    def sortPaths (self):
        self.__sortNode(self.root)

    def __sortNode (self, _node):

        # sort the files based on the file-1st-directory-2nd rule.
        contents = {}
        elements = {}
        for child in _node.getChildNodes():
            if child.nodeType == node.NodeType.Content:
                contents[child.content] = child
            elif child.nodeType == node.NodeType.Element:
                elements[child.name] = child
                self.__sortNode(child)

        # build a new set of child node list.
        children = []

        # contents first.
        contentNames = contents.keys()
        contentNames.sort()
        for name in contentNames:
            children.append(contents[name])

        # elements next.
        elementNames = elements.keys()
        elementNames.sort()
        if _node.nodeType == node.NodeType.Element and _node.name == 'text':
            # 'swriter', 'scalc', 'simpress', 'sdraw', 'schart' are ranked higher in this order.
            l = ['swriter', 'scalc', 'simpress', 'sdraw', 'smath', 'schart']
            newElemNames = []
            for elem in l:
                if elem in elementNames:
                    pos = elementNames.index(elem)
                    poped = elementNames.pop(pos)
                    newElemNames.append(poped)
            newElemNames.extend(elementNames)
            elementNames = newElemNames

        for name in elementNames:
            children.append(elements[name])
        _node.setChildNodes(children)

    def sort (self):
        self.buildPaths()
        self.sortPaths()
        return self.getFilePaths()

    def getFilePaths (self):
        """Return a list of sorted file names."""
        self.filepaths = [] # empty the existing list first.
        self.__walkToContent(self.root)
        return self.filepaths

    def __walkToContent (self, _node):
        if _node.nodeType == node.NodeType.Content:
            s = _node.content
            n = _node.parent
            while n.nodeType == node.NodeType.Element:
                s = n.name + '/' + s
                n = n.parent
            self.filepaths.append(s)
        elif _node.nodeType == node.NodeType.Element or _node.nodeType == node.NodeType.Root:
            for child in _node.getChildNodes():
                self.__walkToContent(child)


class DocBookConverter:

    elemRelTable = {
        'book': 'chapter',
        'chapter': 'sect1',
        'sect1': 'sect2',
        'sect2': 'sect3',
        'sect3': 'sect4',
        'sect4': 'sect5'
    }

    elemIgnored = {
        'comment': 1,
        'history': 1
    }

    itemTypeTable = {
        'keycode': 'keycode',
        'productname': 'productname',
        'input': 'userinput',
        'literal': 'literal',
        'menuitem': 'guimenuitem'
    }

    @staticmethod
    def startSubSection (src):
        if DocBookConverter.elemRelTable.has_key(src.name):
            return src.appendElement(DocBookConverter.elemRelTable[src.name])
        else:
            return None

    def __init__ (self, treeroot, xhproots, embeds):
        self.treeroot = treeroot
        self.xhproots = xhproots
        self.embeds = embeds
        self.root = node.Root()
        self.exthelps = {} # texts for extended helps.
        self.__headingCount = 0
        self.__headingParent = None
        self.__currentFileNameStack = []

    def convert (self):
        book = self.root.appendElement('book')
        bookinfo = book.appendElement('bookinfo')
        title = bookinfo.appendElement('title')
        title.appendContent(globals.productName + " Help")
        
        for section in self.treeroot.getChildNodes():
            self.__walk(section, book)

    def __walk (self, src, dest):
        # src element is either 'section' or 'content'.
        if src.name == 'section':
            title = src.getAttr('title')
            elem = DocBookConverter.startSubSection(dest)
            elem.appendElement('title').appendContent(title)
            for child in src.getChildNodes():
                self.__walk(child, elem)
        elif src.name == 'content':
            # this element has 'title' and 'path' attributes, and has no more child nodes.
            title = src.getAttr('title')
            xhppath = src.getAttr('path')
            sect = DocBookConverter.startSubSection(dest)
#           sect.setAttr('id', xhppath)
            sect.appendElement('title').appendContent(title)
            if self.xhproots.has_key(xhppath):
                self.__getContentFromXHP(xhppath, sect)
            else:
                sect.appendElement('warning').appendContent('get content from ' + src.getAttr('path'))

    def __pushFileName (self, name):
        if len(name) > 0 and name[0] == '/':
            name = name[1:]
        self.__currentFileNameStack.append(name)

    def __popFileName (self):
        self.__currentFileNameStack.pop()

    def __getFileName (self, xhproot):
        self.__currentFileNameStack = []
        helpdoc = xhproot.firstChild()
        if helpdoc == None:
            return
        xhpmeta = helpdoc.firstChildByName('meta')
        topic = xhpmeta.firstChildByName('topic')
        if topic == None:
            return
        filename = topic.firstChildByName('filename')
        if filename == None:
            return
        self.__pushFileName(filename.getContent())

    def __getContentFromXHP (self, xhppath, dest):
        print ("get content from %s"%xhppath)
        xhproot = self.xhproots[xhppath]
        helpdoc = xhproot.firstChild()
        self.__getFileName(xhproot)
        xhpbody = helpdoc.firstChildByName('body')
        # parent element for the xhp 'heading' paragraphs which should start a 
        # new sub-section when converting to docbook.
        self.__headingCount = 0
        self.__headingParent = None
        encodedID = globals.encodeID(self.__currentFileNameStack[-1])
        if len(encodedID) > 0:
            dest.setAttr('id', encodedID) 
        for xhpelem in xhpbody.getChildNodes():
            dest = self.__walkXHP(xhpelem, dest)

    def __getEmbedNode (self, href):
        filename, id = href.split('#')
        if filename.startswith('/'):
            filename = filename[1:]
        if self.embeds.has_key(filename) and self.embeds[filename].has_key(id):
            return self.embeds[filename][id]
        return None

    def __walkAllChildNodes (self, src, dest):
        for child in src.getChildNodes():
            dest = self.__walkXHP(child, dest)

    def __walkTable (self, src, dest):
        table = dest.appendElement('informaltable')
        self.__maybeAddElementID(src, table)
        tgrp = table.appendElement('tgroup')
        # <tgroup> element needs 'cols' attribute to specify column size.
        tbody = tgrp.appendElement('tbody')
        totalColSize = 0
        for trow in src.getChildNodes():
            if trow.nodeType != node.NodeType.Element or trow.name != 'tablerow':
                continue

            row = tbody.appendElement('row')
            colSize = 0
            for tcell in trow.getChildNodes():
                if tcell.nodeType != node.NodeType.Element or tcell.name != 'tablecell':
                    continue
                entry = row.appendElement('entry')
                colspan = tcell.getAttr('colspan')
                colspanNum = 1
                if colspan != None:
                    try:
                        colspanNum = string.atoi(colspan)
                        if colspanNum < 1:
                            colspanNum = 1
                    except ValueError:
                        pass

                colSize += colspanNum
                self.__walkAllChildNodes(tcell, entry)

            if colSize > totalColSize:
                totalColSize = colSize

        tgrp.setAttr('cols', totalColSize)

    def __maybeAddElementID (self, src, dest):
        if dest == None:
            return

        if len(self.__currentFileNameStack) == 0:
            return

        id = src.getAttr('id')
        if id == None:
            return

        idstr = globals.encodeID(self.__currentFileNameStack[-1] + "_" + id)
        if dest.hasAttr('id'):
            dest.appendElement('anchor').setAttr('id', idstr)
        else:
            dest.setAttr('id', idstr)

    def __walkXHP (self, src, dest):

        if src.nodeType == node.NodeType.Content:
            # content node.
            content = src.content
            if len(content.strip()) > 0:
                dest.appendContent(content)
            return dest

        elif DocBookConverter.elemIgnored.has_key(src.name):
            # we can ignore these elements.
            return dest

        if src.name == 'embed' or src.name == 'embedvar':
            # embed takes its content from another xhp file.
            href = src.getAttr('href')
            embed = self.__getEmbedNode(href)
            paraEmbed = (src.name == 'embed')
            if embed == None:
                dest.appendElement('warning').appendContent('take embedded content from ' + href)
            elif paraEmbed:
                self.__pushFileName(href)
                para = dest.appendElement('para')
                self.__walkXHP(embed, para)
                self.__popFileName()
            else:
                self.__pushFileName(href)
                self.__walkXHP(embed, dest)
                self.__popFileName()

        elif src.name == 'switchinline':
            # For now, always select the <defaultinline> child element.
            definline = src.firstChildByName('defaultinline')
            if definline == None:
                dest.appendElement('emphasis').appendContent('{error: switchinline failed to convert due to absense of defaultinline element.}')
            else:
                content = definline.getContent()
                dest.appendContent(content)
            
        elif src.name == 'item':
            # an <item> element has a 'type' attribute that specifies how this 
            # text span should be formatted.
            itemType = src.getAttr('type')
            if DocBookConverter.itemTypeTable.has_key(itemType):
                dest.appendElement(DocBookConverter.itemTypeTable[itemType]).appendContent(src.getContent())
            else:
                dest.appendElement('emphasis').appendContent("{%s: %s}"%(itemType, src.getContent()))

        elif src.name == 'list':
            # type may be 'unordered' (bulleted) or 'ordered' (numbered).
            listType = src.getAttr('type')
            lnode = None
            if listType == 'unordered':
                lnode = dest.appendElement('itemizedlist')
            elif listType == 'ordered':
                lnode = dest.appendElement('orderedlist')
            
            if lnode != None:
                self.__walkAllChildNodes(src, lnode)
            else:
                dest.appendElement('warning').appendContent('unknown list type: ' + listType)

        elif src.name == 'listitem':
            # This one needs no translation.
            li = dest.appendElement('listitem')
            self.__walkAllChildNodes(src, li)

        elif src.name == 'link':
            href = src.getAttr('href')
            link = dest.appendElement('link')
            if not href.startswith('http'):
                href = globals.encodeID(href)
            link.setAttr('linkend', href)
            self.__walkAllChildNodes(src, link)

        elif src.name == 'ahelp':
            # this tag is used for extended tips from the application.  Let's 
            # store the content of this element for later use.
            if src.hasAttr('hid'):
                hid = src.getAttr('hid')
                self.exthelps[hid] = src.getContent()

            visible = True
            if src.hasAttr('visibility'):
                visible = src.getAttr('visibility') == 'visible'
            if visible:
                self.__walkAllChildNodes(src, dest)

        elif src.name == 'sort':
            # A <sort> element has an 'order' attribute that can be either 'asc' or 'desc'.
            # It has <section> elements as its immediate child elements, and each <section>
            # has an 'id' attribute whose value is to be used for sorting.
            order = src.getAttr('order')
            sections = src.getChildByName('section')
            sectionMap = {}
            for sec in sections:
                sectionMap[sec.getAttr('id')] = sec
            keys = sectionMap.keys()
            if order == 'asc':
                keys.sort()
            else:
                keys.reverse()
            for key in keys:
                sec = sectionMap[key]
                self.__walkAllChildNodes(sec, dest)

        elif src.name == 'paragraph':
            # normal paragraph content.
            role = src.getAttr('role')
            if role == None:
                role = ''
            if role == 'heading':
                # We can't reliably use the heading levels to structure the 
                # document, since the levels are used inconsistently in the 
                # original xhp files.
                if self.__headingCount == 0:
                    # Ignore the very first heading.
                    self.__headingParent = None
                else:
                    if self.__headingParent == None:
                        self.__headingParent = dest
                    else:
                        dest = self.__headingParent
                    dest = dest.appendElement('formalpara')
                    self.__maybeAddElementID(src, dest)
                    title = dest.appendElement('title')
                    self.__walkAllChildNodes(src, title)

                self.__headingCount += 1

            elif role == 'code':
                proglisting = dest.appendElement('programlisting')
                self.__walkAllChildNodes(src, proglisting)
            else:
                paraName = 'para'
                if role == 'note':
                    paraName = 'note'
                elif role == 'warning':
                    paraName = 'caution'
                elif role == 'tip':
                    paraName = 'tip'
                para = dest.appendElement(paraName)
                self.__walkAllChildNodes(src, para)

        elif src.name == 'emph':
            dest.appendElement('emphasis').appendContent(src.getContent())

        elif src.name == 'section':
            if src.getAttr('id') == 'howtoget':
                elem = dest.appendElement('tip')
                elem.appendElement('title').appendContent('To access this command...')
                self.__maybeAddElementID(src, elem)
                self.__walkAllChildNodes(src, elem)
            else:
                self.__maybeAddElementID(src, dest)
                self.__walkAllChildNodes(src, dest)
            
        elif src.name == 'variable':
            self.__walkAllChildNodes(src, dest)

        elif src.name == 'table':
            self.__walkTable(src, dest)

        elif src.name == 'br':
            # if this occurs inside a <para> element, end the current paragraph, 
            # and start a new one at the same level.
            if dest.name == 'para':
                dest = dest.parent.appendElement('para')

        elif src.name == 'bookmark':
            # For now, I ignore the 'contents' branch.
            branch = src.getAttr('branch')
            if branch == None:
                branch = ''

            if branch == 'index':
                values = src.getChildByName('bookmark_value')
                for value in values:
                    indexterm = dest.appendElement('indexterm')
                    strlist = value.getContent().split(';')
                    for i in xrange(0, len(strlist)):
                        s = strlist[i].strip()
                        if i == 0:
                            indexterm.appendElement('primary').appendContent(s)
                        elif i == 1:
                            indexterm.appendElement('secondary').appendContent(s)
                        elif i == 2:
                            indexterm.appendElement('tertiary').appendContent(s)
            elif branch.startswith('hid/'):
                hid = branch[4:]
                dest.appendElement('anchor').setAttr('id', hid)

        else:
            # unhandled element.  My work is done when these elements go away.
            dest.appendElement('warning').appendContent("unhandled element '%s'"%src.name)

        return dest


    def prettyPrint (self, fd):
        node.prettyPrint(fd, self.root)