#!/usr/bin/env python

"""

:Author: Ollie Rutherfurd

:Contact: oliver@rutherfurd.net

:Revision: $Revision: 5918 $

:Date: $Date: 2009-04-23 04:45:57 +0200 (Don, 23 Apr 2009) $

:Copyright: This module has been placed in the public domain.

DocBook XML document tree Writer.

This Writer converts a reST document tree to a subset

of DocBook.

**This is an unfinished work in progress.**

"""

__docformat__ = 'reStructuredText'

import re

import string

from docutils import writers, nodes, languages

from types import ListType

class Writer(writers.Writer):

    settings_spec = (

        'DocBook-Specific Options',

        None,

        (('Set DocBook document type. '

            'Choices are "article", "book", and "chapter". '

            'Default is "article".',

            ['--doctype'],

            {'default': 'chapter', 

             'metavar': '<name>',

             'type': 'choice', 

             'choices': ('article', 'book', 'chapter',)

            }

         ),

        )

    )

    """DocBook does it's own section numbering"""

    settings_default_overrides = {'enable_section_numbering': 0}

    output = None

    """Final translated form of `document`."""

    def translate(self):

        visitor = DocBookTranslator(self.document)

        self.document.walkabout(visitor)

        self.output = visitor.astext()

class DocBookTranslator(nodes.NodeVisitor):

    XML_DECL = '<?xml version="1.0" encoding="%s"?>\n'

    DOCTYPE_DECL = """<!DOCTYPE %s 

        PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\n"""

    def __init__(self, document):

        nodes.NodeVisitor.__init__(self, document)

        self.language = languages.get_language(

            document.settings.language_code)

        self.doctype = document.settings.doctype

        self.doc_header = [

            self.XML_DECL % (document.settings.output_encoding,),

            self.DOCTYPE_DECL % (self.doctype,),

            '<%s>\n' % (self.doctype,),

        ]

        self.doc_footer = [

            '</%s>\n' % (self.doctype,)

        ]

        self.body = []

        self.section = 0

        self.context = []

        self.colnames = []

        self.footnotes = {}

        self.footnote_map = {}

        self.docinfo = []

        self.title = ''

        self.subtitle = ''

    def astext(self):

        return ''.join(self.doc_header

                    + self.docinfo

                    + self.body

                    + self.doc_footer)

    def encode(self, text):

        """Encode special characters in `text` & return."""

        # @@@ A codec to do these and all other 

        # HTML entities would be nice.

        text = text.replace("&", "&")

        text = text.replace("<", "&lt;")

        text = text.replace('"', """)

        text = text.replace(">", ">")

        return text

    def encodeattr(self, text):

        """Encode attributes characters > 128 as &#XXX;"""

        buff = []

        for c in text:

            if ord(c) >= 128:

                buff.append('&#%d;' % ord(c))

            else:

                buff.append(c)

        return ''.join(buff)

    def rearrange_footnotes(self):

        """

        Replaces ``foonote_reference`` placeholders with

        ``footnote`` element content as DocBook and reST

        handle footnotes differently.

        DocBook defines footnotes inline, whereas they

        may be anywere in reST.  This function replaces the 

        first instance of a ``footnote_reference`` with 

        the ``footnote`` element itself, and later 

        references of the same a  footnote with 

        ``footnoteref`` elements.

        """

        for (footnote_id,refs) in self.footnote_map.items():

            ref_id, context, pos = refs[0]

            context[pos] = ''.join(self.footnotes[footnote_id])

            for ref_id, context, pos in refs[1:]:

                context[pos] = '<footnoteref linkend="%s"/>' \

                    % (footnote_id,)

    def attval(self, text,

               transtable=string.maketrans('\n\r\t\v\f', '     ')):

        """Cleanse, encode, and return attribute value text."""

        return self.encode(text.translate(transtable))

    def starttag(self, node, tagname, suffix='\n', infix='', **attributes):

        """

        Construct and return a start tag given a node 

        (id & class attributes are extracted), tag name, 

        and optional attributes.

        """

        atts = {}

        for (name, value) in attributes.items():

            atts[name.lower()] = value

        for att in ('id',):             # node attribute overrides

            if node.has_key(att):

                atts[att] = node[att]

        attlist = atts.items()

        attlist.sort()

        parts = [tagname.lower()]

        for name, value in attlist:

            if value is None:           # boolean attribute

                # this came from the html writer, but shouldn't

                # apply here, as an element with no attribute

                # isn't well-formed XML.

                parts.append(name.lower())

            elif isinstance(value, ListType):

                values = [str(v) for v in value]

                parts.append('%s="%s"' % (name.lower(),

                                          self.attval(' '.join(values))))

            else:

                name = self.encodeattr(name.lower())

                value = str(self.encodeattr(unicode(value)))

                value = self.attval(value)

                parts.append('%s="%s"' % (name,value))

        return '<%s%s>%s' % (' '.join(parts), infix, suffix)

    def emptytag(self, node, tagname, suffix='\n', **attributes):

        """Construct and return an XML-compatible empty tag."""

        return self.starttag(node, tagname, suffix, infix=' /', **attributes)

    def visit_Text(self, node):

        self.body.append(self.encode(node.astext()))

    def depart_Text(self, node):

        pass

    def visit_address(self, node):

        # handled by visit_docinfo

        pass

    def depart_address(self, node):

        # handled by visit_docinfo

        pass

    def visit_admonition(self, node, name=''):

        self.body.append(self.starttag(node, 'note'))

    def depart_admonition(self, node=None):

        self.body.append('</note>\n')

    def visit_attention(self, node):

        self.body.append(self.starttag(node, 'note'))

        self.body.append('\n<title>%s</title>\n' 

            % (self.language.labels[node.tagname],))

    def depart_attention(self, node):

        self.body.append('</note>\n')

    def visit_attribution(self, node):

        # attribution must precede blockquote content

        if isinstance(node.parent, nodes.block_quote):

            raise nodes.SkipNode

        self.body.append(self.starttag(node, 'attribution', ''))

    def depart_attribution(self, node):

        # attribution must precede blockquote content

        if not isinstance(node.parent, nodes.block_quote):

            self.body.append('</attribution>\n')

    # author is handled in ``visit_docinfo()``

    def visit_author(self, node):

        raise nodes.SkipNode

    # authors is handled in ``visit_docinfo()``

    def visit_authors(self, node):

        raise nodes.SkipNode

    def visit_block_quote(self, node):

        self.body.append(self.starttag(node, 'blockquote'))

        if isinstance(node[-1], nodes.attribution):

            self.body.append('<attribution>%s</attribution>\n' % node[-1].astext())

    def depart_block_quote(self, node):

        self.body.append('</blockquote>\n')

    def visit_bullet_list(self, node):

        self.body.append(self.starttag(node, 'itemizedlist'))

    def depart_bullet_list(self, node):

        self.body.append('</itemizedlist>\n')

    def visit_caption(self, node):

        # NOTE: ideally, this should probably be stuffed into

        # the mediaobject as a "caption" element

        self.body.append(self.starttag(node, 'para'))

    def depart_caption(self, node):

        self.body.append('</para>')

    def visit_caution(self, node):

        self.body.append(self.starttag(node, 'caution'))

        self.body.append('\n<title>%s</title>\n' 

            % (self.language.labels[node.tagname],))

    def depart_caution(self, node):

        self.body.append('</caution>\n')

    # reST & DocBook ciations are somewhat 

    # different creatures.

    #

    # reST seems to handle citations as a labled

    # footnotes, whereas DocBook doesn't from what

    # I can tell.  In DocBook, it looks like they're

    # an abbreviation for a published work, which 

    # might be in the bibliography.

    #

    # Quote:

    #

    #   The content of a Citation is assumed to be a reference 

    #   string, perhaps identical to an abbreviation in an entry 

    #   in a Bibliography. 

    #

    # I hoped to have citations behave look footnotes,

    # using the citation label as the footnote label,

    # which would seem functionally equivlent, however

    # the DocBook stylesheets for generating HTML & FO 

    # output don't seem to be using the label for foonotes

    # so this doesn't work very well.

    #

    # Any ideas or suggestions would be welcome.

    def visit_citation(self, node):

        self.visit_footnote(node)

    def depart_citation(self, node):

        self.depart_footnote(node)

    def visit_citation_reference(self, node):

        self.visit_footnote_reference(node)

    def depart_citation_reference(self, node):

        # there isn't a a depart_footnote_reference

        pass

    def visit_classifier(self, node):

        self.body.append(self.starttag(node, 'type'))

    def depart_classifier(self, node):

        self.body.append('</type>\n')

    def visit_colspec(self, node):

        self.colnames.append('col_%d' % (len(self.colnames) + 1,))

        atts = {'colname': self.colnames[-1]}

        self.body.append(self.emptytag(node, 'colspec', **atts))

    def depart_colspec(self, node):

        pass

    def visit_comment(self, node, sub=re.compile('-(?=-)').sub):

        """Escape double-dashes in comment text."""

        self.body.append('<!-- %s -->\n' % sub('- ', node.astext()))

        raise nodes.SkipNode

    # contact is handled in ``visit_docinfo()``

    def visit_contact(self, node):

        raise nodes.SkipNode

    # copyright is handled in ``visit_docinfo()``

    def visit_copyright(self, node):

        raise nodes.SkipNode

    def visit_danger(self, node):

        self.body.append(self.starttag(node, 'caution'))

        self.body.append('\n<title>%s</title>\n' 

            % (self.language.labels[node.tagname],))

    def depart_danger(self, node):

        self.body.append('</caution>\n')

    # date is handled in ``visit_docinfo()``

    def visit_date(self, node):

        raise nodes.SkipNode

    def visit_decoration(self, node):

        pass

    def depart_decoration(self, node):

        pass

    def visit_definition(self, node):

        # "term" is not closed in depart_term

        self.body.append('</term>\n')

        self.body.append(self.starttag(node, 'listitem'))

    def depart_definition(self, node):

        self.body.append('</listitem>\n')

    def visit_definition_list(self, node):

        self.body.append(self.starttag(node, 'variablelist'))

    def depart_definition_list(self, node):

        self.body.append('</variablelist>\n')

    def visit_definition_list_item(self, node):

        self.body.append(self.starttag(node, 'varlistentry'))

    def depart_definition_list_item(self, node):

        self.body.append('</varlistentry>\n')

    def visit_description(self, node):

        self.body.append(self.starttag(node, 'entry'))

    def depart_description(self, node):

        self.body.append('</entry>\n')

    def visit_docinfo(self, node):

        """

        Collects all docinfo elements for the document.

        Since reST's bibliography elements don't map very

        cleanly to DocBook, rather than maintain state and

        check dependencies within the different visitor

        fuctions all processing of bibliography elements

        is dont within this function.

        .. NOTE:: Skips processing of all child nodes as

                  everything should be collected here.

        """

        # XXX There are a number of fields in docinfo elements

        #     which don't map nicely to docbook elements and 

        #     reST allows one to insert arbitrary fields into

        #     the header, We need to be able to handle fields

        #     which either don't map or nicely or are unexpected.

        #     I'm thinking of just using DocBook to display these

        #     elements in some sort of tabular format -- but

        #     to collecting them is not straight-forward.  

        #     Paragraphs, links, lists, etc... can all live within

        #     the values so we either need a separate visitor

        #     to translate these elements, or to maintain state

        #     in any possible child elements (not something I

        #     want to do).

        docinfo = ['<%sinfo>\n' % self.doctype]

        address = ''

        authors = []

        author = ''

        contact = ''

        date = ''

        legalnotice = ''

        orgname = ''

        releaseinfo = ''

        revision,version = '',''

        docinfo.append('<title>%s</title>\n' % self.title)

        if self.subtitle:

            docinfo.append('<subtitle>%s</subtitle>\n' % self.subtitle)

        for n in node:

            if isinstance(n, nodes.address):

                address = n.astext()

            elif isinstance(n, nodes.author):

                author = n.astext()

            elif isinstance(n, nodes.authors):

                for a in n:

                    authors.append(a.astext())

            elif isinstance(n, nodes.contact):

                contact = n.astext()

            elif isinstance(n, nodes.copyright):

                legalnotice = n.astext()

            elif isinstance(n, nodes.date):

                date = n.astext()

            elif isinstance(n, nodes.organization):

                orgname = n.astext()

            elif isinstance(n, nodes.revision):

                # XXX yuck

                revision = 'Revision ' + n.astext()

            elif isinstance(n, nodes.status):

                releaseinfo = n.astext()

            elif isinstance(n, nodes.version):

                # XXX yuck

                version = 'Version ' + n.astext()

            elif isinstance(n, nodes.field):

                # XXX

                import sys

                print >> sys.stderr, "I don't do 'field' yet"

                print n.astext()

            # since all child nodes are handled here raise an exception

            # if node is not handled, so it doesn't silently slip through.

            else:

                print dir(n)

                print n.astext()

                raise self.unimplemented_visit(n)

        # can only add author if name is present

        # since contact is associate with author, the contact

        # can also only be added if an author name is given.

        if author:

            docinfo.append('<author>\n')

            docinfo.append('<othername>%s</othername>\n' % author)

            if contact:

                docinfo.append('<email>%s</email>\n' % contact)

            docinfo.append('</author>\n')

        if authors:

            docinfo.append('<authorgroup>\n')

            for name in authors:

                docinfo.append(

                    '<author><othername>%s</othername></author>\n' % name)

            docinfo.append('</authorgroup>\n')

        if revision or version:

            edition = version

            if edition and revision:

                edition += ', ' + revision

            elif revision:

                edition = revision

            docinfo.append('<edition>%s</edition>\n' % edition)

        if date:

            docinfo.append('<date>%s</date>\n' % date)

        if orgname:

            docinfo.append('<orgname>%s</orgname>\n' % orgname)

        if releaseinfo:

            docinfo.append('<releaseinfo>%s</releaseinfo>\n' % releaseinfo)

        if legalnotice:

            docinfo.append('<legalnotice>\n')

            docinfo.append('<para>%s</para>\n' % legalnotice)

            docinfo.append('</legalnotice>\n')

        if address:

            docinfo.append('<address xml:space="preserve">' + 

                address + '</address>\n')

        if len(docinfo) > 1:

            docinfo.append('</%sinfo>\n' % self.doctype)

        self.docinfo = docinfo

        raise nodes.SkipChildren

    def depart_docinfo(self, node):

        pass

    def visit_doctest_block(self, node):

        self.body.append('<informalexample>\n')

        self.body.append(self.starttag(node, 'programlisting'))

    def depart_doctest_block(self, node):

        self.body.append('</programlisting>\n')

        self.body.append('</informalexample>\n')

    def visit_document(self, node):

        pass

    def depart_document(self, node):

        self.rearrange_footnotes()

    def visit_emphasis(self, node):

        self.body.append('<emphasis>')

    def depart_emphasis(self, node):

        self.body.append('</emphasis>')

    def visit_entry(self, node):

        tagname = 'entry'

        atts = {}

        if node.has_key('morerows'):

            atts['morerows'] = node['morerows']

        if node.has_key('morecols'):

            atts['namest'] = self.colnames[self.entry_level]

            atts['nameend'] = self.colnames[self.entry_level \

                + node['morecols']]

        self.entry_level += 1   # for tracking what namest and nameend are

        self.body.append(self.starttag(node, tagname, '', **atts))

    def depart_entry(self, node):

        self.body.append('</entry>\n')

    def visit_enumerated_list(self, node):