# $Id: __init__.py 5174 2007-05-31 00:01:52Z wiemann $

# Author: Lea Wiemann <LeWiemann@gmail.com>

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

"""

LaTeX2e document tree Writer.

"""

# Thanks to Engelbert Gruber and various contributors for the original

# LaTeX writer, some code and many ideas of which have been used for

# this writer.

__docformat__ = 'reStructuredText'

import re

import os.path

from types import ListType

import docutils

from docutils import nodes, writers, utils

from docutils.writers.newlatex2e import unicode_map

from docutils.transforms import writer_aux

class Writer(writers.Writer):

    supported = ('newlatex', 'newlatex2e')

    """Formats this writer supports."""

    default_stylesheet = 'base.tex'

    default_stylesheet_path = utils.relative_path(

        os.path.join(os.getcwd(), 'dummy'),

        os.path.join(os.path.dirname(__file__), default_stylesheet))

    settings_spec = (

        'LaTeX-Specific Options',

        'Note that this LaTeX writer is still EXPERIMENTAL and not '

        'feature-complete. ',

        (('Specify a stylesheet file.  The path is used verbatim to include '

          'the file.  Overrides --stylesheet-path.',

          ['--stylesheet'],

          {'default': '', 'metavar': '<file>',

           'overrides': 'stylesheet_path'}),

         ('Specify a stylesheet file, relative to the current working '

          'directory.  Overrides --stylesheet.  Default: "%s"'

          % default_stylesheet_path,

          ['--stylesheet-path'],

          {'metavar': '<file>', 'overrides': 'stylesheet',

           'default': default_stylesheet_path}),

         ('Specify a user stylesheet file.  See --stylesheet.',

          ['--user-stylesheet'],

          {'default': '', 'metavar': '<file>',

           'overrides': 'user_stylesheet_path'}),

         ('Specify a user stylesheet file.  See --stylesheet-path.',

          ['--user-stylesheet-path'],

          {'metavar': '<file>', 'overrides': 'user_stylesheet'})

         ),)

    settings_defaults = {

        # Many Unicode characters are provided by unicode_map.py, so

        # we can default to latin-1.

        'output_encoding': 'latin-1',

        'output_encoding_error_handler': 'strict',

        # Since we are using superscript footnotes, it is necessary to

        # trim whitespace in front of footnote references.

        'trim_footnote_reference_space': 1,

        # Currently unsupported:

        'docinfo_xform': 0,

        # During development:

        'traceback': 1

        }

    relative_path_settings = ('stylesheet_path', 'user_stylesheet_path')

    config_section = 'newlatex2e writer'

    config_section_dependencies = ('writers',)

    output = None

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

    def get_transforms(self):

        return writers.Writer.get_transforms(self) + [

            writer_aux.Compound, writer_aux.Admonitions]

    def __init__(self):

        writers.Writer.__init__(self)

        self.translator_class = LaTeXTranslator

    def translate(self):

        visitor = self.translator_class(self.document)

        self.document.walkabout(visitor)

        assert not visitor.context, 'context not empty: %s' % visitor.context

        self.output = visitor.astext()

        self.head = visitor.header

        self.body = visitor.body

class LaTeXException(Exception):

    """

    Exception base class to for exceptions which influence the

    automatic generation of LaTeX code.

    """

class SkipAttrParentLaTeX(LaTeXException):

    """

    Do not generate ``\DECattr`` and ``\renewcommand{\DEVparent}{...}`` for this

    node.

    To be raised from ``before_...`` methods.

    """

class SkipParentLaTeX(LaTeXException):

    """

    Do not generate ``\renewcommand{\DEVparent}{...}`` for this node.

    To be raised from ``before_...`` methods.

    """

class LaTeXTranslator(nodes.SparseNodeVisitor):

    # Country code by a.schlock.

    # Partly manually converted from iso and babel stuff.

    iso639_to_babel = {

        'no': 'norsk',     # added by hand

        'gd': 'scottish',  # added by hand

        'sl': 'slovenian',

        'af': 'afrikaans',

        'bg': 'bulgarian',

        'br': 'breton',

        'ca': 'catalan',

        'cs': 'czech',

        'cy': 'welsh',

        'da': 'danish',

        'fr': 'french',

        # french, francais, canadien, acadian

        'de': 'ngerman',

        # ngerman, naustrian, german, germanb, austrian

        'el': 'greek',

        'en': 'english',

        # english, USenglish, american, UKenglish, british, canadian

        'eo': 'esperanto',

        'es': 'spanish',

        'et': 'estonian',

        'eu': 'basque',

        'fi': 'finnish',

        'ga': 'irish',

        'gl': 'galician',

        'he': 'hebrew',

        'hr': 'croatian',

        'hu': 'hungarian',

        'is': 'icelandic',

        'it': 'italian',

        'la': 'latin',

        'nl': 'dutch',

        'pl': 'polish',

        'pt': 'portuguese',

        'ro': 'romanian',

        'ru': 'russian',

        'sk': 'slovak',

        'sr': 'serbian',

        'sv': 'swedish',

        'tr': 'turkish',

        'uk': 'ukrainian'

    }

    # Start with left double quote.

    left_quote = 1

    def __init__(self, document):

        nodes.NodeVisitor.__init__(self, document)

        self.settings = document.settings

        self.header = []

        self.body = []

        self.context = []

        self.stylesheet_path = utils.get_stylesheet_reference(

            self.settings, os.path.join(os.getcwd(), 'dummy'))

        if self.stylesheet_path:

            self.settings.record_dependencies.add(self.stylesheet_path)

        # This ugly hack will be cleaned up when refactoring the

        # stylesheet mess.

        self.settings.stylesheet = self.settings.user_stylesheet

        self.settings.stylesheet_path = self.settings.user_stylesheet_path

        self.user_stylesheet_path = utils.get_stylesheet_reference(

            self.settings, os.path.join(os.getcwd(), 'dummy'))

        if self.user_stylesheet_path:

            self.settings.record_dependencies.add(self.user_stylesheet_path)

        self.write_header()

    def write_header(self):

        a = self.header.append

        a('%% Generated by Docutils %s <http://docutils.sourceforge.net>.'

          % docutils.__version__)

        a('')

        a('% Docutils settings:')

        lang = self.settings.language_code or ''

        a(r'\providecommand{\DEVlanguageiso}{%s}' % lang)

        a(r'\providecommand{\DEVlanguagebabel}{%s}' % self.iso639_to_babel.get(

            lang, self.iso639_to_babel.get(lang.split('_')[0], '')))

        a('')

        if self.user_stylesheet_path:

            a('% User stylesheet:')

            a(r'\input{%s}' % self.user_stylesheet_path)

        a('% Docutils stylesheet:')

        a(r'\input{%s}' % self.stylesheet_path)

        a('')

        a('% Default definitions for Docutils nodes:')

        for node_name in nodes.node_class_names:

            a(r'\providecommand{\DN%s}[1]{#1}' % node_name.replace('_', ''))

        a('')

        a('% Auxiliary definitions:')

        for attr in (r'\DEVparent \DEVattrlen \DEVtitleastext '

                     r'\DEVsinglebackref \DEVmultiplebackrefs'

                     ).split():

            # Later set using \renewcommand.

            a(r'\providecommand{%s}{DOCUTILSUNINITIALIZEDVARIABLE}' % attr)

        for attr in (r'\DEVparagraphindented \DEVhassubtitle').split():

            # Initialize as boolean variables.

            a(r'\providecommand{%s}{false}' % attr)

        a('\n\n')

    unicode_map = unicode_map.unicode_map # comprehensive Unicode map

    # Fix problems with unimap.py.

    unicode_map.update({

        # We have AE or T1 encoding, so "``" etc. work.  The macros

        # from unimap.py may *not* work.

        u'\u201C': '{``}',

        u'\u201D': "{''}",

        u'\u201E': '{,,}',

        })

    character_map = {

        '\\': r'{\textbackslash}',

        '{': r'{\{}',

        '}': r'{\}}',

        '$': r'{\$}',

        '&': r'{\&}',

        '%': r'{\%}',

        '#': r'{\#}',

        '[': r'{[}',

        ']': r'{]}',

        '-': r'{-}',

        '`': r'{`}',

        "'": r"{'}",

        ',': r'{,}',

        '"': r'{"}',

        '|': r'{\textbar}',

        '<': r'{\textless}',

        '>': r'{\textgreater}',

        '^': r'{\textasciicircum}',

        '~': r'{\textasciitilde}',

        '_': r'{\DECtextunderscore}',

        }

    character_map.update(unicode_map)

    #character_map.update(special_map)

    # `att_map` is for encoding attributes.  According to

    # <http://www-h.eng.cam.ac.uk/help/tpl/textprocessing/teTeX/latex/latex2e-html/ltx-164.html>,

    # the following characters are special: # $ % & ~ _ ^ \ { }

    # These work without special treatment in macro parameters:

    # $, &, ~, _, ^

    att_map = {'#': '\\#',

               '%': '\\%',

               # We cannot do anything about backslashes.

               '\\': '',

               '{': '\\{',

               '}': '\\}',

               # The quotation mark may be redefined by babel.

               '"': '"{}',

               }

    att_map.update(unicode_map)

    def encode(self, text, attval=None):

        """

        Encode special characters in ``text`` and return it.

        If attval is true, preserve as much as possible verbatim (used

        in attribute value encoding).  If attval is 'width' or

        'height', `text` is interpreted as a length value.

        """

        if attval in ('width', 'height'):

            match = re.match(r'([0-9.]+)(\S*)$', text)

            assert match, '%s="%s" must be a length' % (attval, text)

            value, unit = match.groups()

            if unit == '%':

                value = str(float(value) / 100)

                unit = r'\DECrelativeunit'

            elif unit in ('', 'px'):

                # If \DECpixelunit is "pt", this gives the same notion

                # of pixels as graphicx.  This is a bit of a hack.

                value = str(float(value) * 0.75)

                unit = '\DECpixelunit'

            return '%s%s' % (value, unit)

        if attval:

            get = self.att_map.get

        else:

            get = self.character_map.get

        text = ''.join([get(c, c) for c in text])

        if (self.literal_block or self.inline_literal) and not attval:

            # NB: We can have inline literals within literal blocks.

            # Shrink '\r\n'.

            text = text.replace('\r\n', '\n')

            # Convert space.  If "{ }~~~~~" is wrapped (at the

            # brace-enclosed space "{ }"), the following non-breaking

            # spaces ("~~~~") do *not* wind up at the beginning of the

            # next line.  Also note that no hyphenation is done if the

            # breaking space ("{ }") comes *after* the non-breaking

            # spaces.

            if self.literal_block:

                # Replace newlines with real newlines.

                text = text.replace('\n', '\mbox{}\\\\{}')

                replace_fn = self.encode_replace_for_literal_block_spaces

            else:

                replace_fn = self.encode_replace_for_inline_literal_spaces

            text = re.sub(r'\s+', replace_fn, text)

            # Protect hyphens; if we don't, line breaks will be

            # possible at the hyphens and even the \textnhtt macro

            # from the hyphenat package won't change that.

            text = text.replace('-', r'\mbox{-}')

            text = text.replace("'", r'{\DECtextliteralsinglequote}')

            return text

        else:

            if not attval:

                # Replace space with single protected space.

                text = re.sub(r'\s+', '{ }', text)

                # Replace double quotes with macro calls.

                L = []

                for part in text.split(self.character_map['"']):

                    if L:

                        # Insert quote.

                        L.append(self.left_quote and r'{\DECtextleftdblquote}'

                                 or r'{\DECtextrightdblquote}')

                        self.left_quote = not self.left_quote

                    L.append(part)

                return ''.join(L)

            else:

                return text

    def encode_replace_for_literal_block_spaces(self, match):

        return '~' * len(match.group())

    def encode_replace_for_inline_literal_spaces(self, match):

        return '{ }' + '~' * (len(match.group()) - 1)

    def astext(self):

        return '\n'.join(self.header) + (''.join(self.body))

    def append(self, text, newline='%\n'):

        """

        Append text, stripping newlines, producing nice LaTeX code.

        """

        lines = ['  ' * self.indentation_level + line + newline

                 for line in text.splitlines(0)]

        self.body.append(''.join(lines))

    def visit_Text(self, node):

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

    def depart_Text(self, node):

        pass

    def is_indented(self, paragraph):

        """Return true if `paragraph` should be first-line-indented."""

        assert isinstance(paragraph, nodes.paragraph)

        siblings = [n for n in paragraph.parent if

                    self.is_visible(n) and not isinstance(n, nodes.Titular)]

        index = siblings.index(paragraph)

        if ('continued' in paragraph['classes'] or

            index > 0 and isinstance(siblings[index-1], nodes.transition)):

            return 0

        # Indent all but the first paragraphs.

        return index > 0

    def before_paragraph(self, node):

        self.append(r'\renewcommand{\DEVparagraphindented}{%s}'

                    % (self.is_indented(node) and 'true' or 'false'))

    def before_title(self, node):

        self.append(r'\renewcommand{\DEVtitleastext}{%s}'

                    % self.encode(node.astext()))

        self.append(r'\renewcommand{\DEVhassubtitle}{%s}'

                    % ((len(node.parent) > 2 and

                        isinstance(node.parent[1], nodes.subtitle))

                       and 'true' or 'false'))

    def before_generated(self, node):

        if 'sectnum' in node['classes']:

            node[0] = node[0].strip()

    literal_block = 0

    def visit_literal_block(self, node):

        self.literal_block = 1

    def depart_literal_block(self, node):

        self.literal_block = 0

    visit_doctest_block = visit_literal_block

    depart_doctest_block = depart_literal_block

    inline_literal = 0

    def visit_literal(self, node):

        self.inline_literal += 1

    def depart_literal(self, node):

        self.inline_literal -= 1

    def _make_encodable(self, text):

        """

        Return text (a unicode object) with all unencodable characters

        replaced with '?'.

        Thus, the returned unicode string is guaranteed to be encodable.

        """

        encoding = self.settings.output_encoding

        return text.encode(encoding, 'replace').decode(encoding)

    def visit_comment(self, node):

        """

        Insert the comment unchanged into the document, replacing

        unencodable characters with '?'.

        (This is done in order not to fail if comments contain unencodable

        characters, because our default encoding is not UTF-8.)

        """

        self.append('\n'.join(['% ' + self._make_encodable(line) for line

                               in node.astext().splitlines(0)]), newline='\n')

        raise nodes.SkipChildren

    def before_topic(self, node):

        if 'contents' in node['classes']:

            for bullet_list in list(node.traverse(nodes.bullet_list)):

                p = bullet_list.parent

                if isinstance(p, nodes.list_item):

                    p.parent.insert(p.parent.index(p) + 1, bullet_list)

                    del p[1]

            for paragraph in node.traverse(nodes.paragraph):

                paragraph.attributes.update(paragraph[0].attributes)

                paragraph[:] = paragraph[0]

                paragraph.parent['tocrefid'] = paragraph['refid']

            node['contents'] = 1

        else:

            node['contents'] = 0

    bullet_list_level = 0

    def visit_bullet_list(self, node):

        self.append(r'\DECsetbullet{\labelitem%s}' %

                    ['i', 'ii', 'iii', 'iv'][min(self.bullet_list_level, 3)])

        self.bullet_list_level += 1

    def depart_bullet_list(self, node):

        self.bullet_list_level -= 1

    enum_styles = {'arabic': 'arabic', 'loweralpha': 'alph', 'upperalpha':

                   'Alph', 'lowerroman': 'roman', 'upperroman': 'Roman'}

    enum_counter = 0

    def visit_enumerated_list(self, node):

        # We create our own enumeration list environment.  This allows

        # to set the style and starting value and unlimited nesting.

        # Maybe the actual creation (\DEC) can be moved to the

        # stylesheet?

        self.enum_counter += 1

        enum_prefix = self.encode(node['prefix'])

        enum_suffix = self.encode(node['suffix'])

        enum_type = '\\' + self.enum_styles.get(node['enumtype'], r'arabic')

        start = node.get('start', 1) - 1

        counter = 'Denumcounter%d' % self.enum_counter

        self.append(r'\DECmakeenumeratedlist{%s}{%s}{%s}{%s}{%s}{'

                    % (enum_prefix, enum_type, enum_suffix, counter, start))

                    # for Emacs: }

    def depart_enumerated_list(self, node):

        self.append('}')  # for Emacs: {

    def before_list_item(self, node):

        # XXX needs cleanup.

        if (len(node) and (isinstance(node[-1], nodes.TextElement) or

                           isinstance(node[-1], nodes.Text)) and

            node.parent.index(node) == len(node.parent) - 1):

            node['lastitem'] = 'true'

    before_line = before_list_item

    def before_raw(self, node):

        if 'latex' in node.get('format', '').split():

            # We're inserting the text in before_raw and thus outside

            # of \DN... and \DECattr in order to make grouping with

            # curly brackets work.

            self.append(node.astext())

        raise nodes.SkipChildren

    def process_backlinks(self, node, type):

        """

        Add LaTeX handling code for backlinks of footnote or citation

        node `node`.  `type` is either 'footnote' or 'citation'.

        """

        self.append(r'\renewcommand{\DEVsinglebackref}{}')

        self.append(r'\renewcommand{\DEVmultiplebackrefs}{}')

        if len(node['backrefs']) > 1:

            refs = []

            for i in range(len(node['backrefs'])):

                # \DECmulticitationbacklink or \DECmultifootnotebacklink.

                refs.append(r'\DECmulti%sbacklink{%s}{%s}'

                            % (type, node['backrefs'][i], i + 1))

            self.append(r'\renewcommand{\DEVmultiplebackrefs}{(%s){ }}'

                        % ', '.join(refs))

        elif len(node['backrefs']) == 1:

            self.append(r'\renewcommand{\DEVsinglebackref}{%s}'

                        % node['backrefs'][0])

    def visit_footnote(self, node):

        self.process_backlinks(node, 'footnote')

    def visit_citation(self, node):

        self.process_backlinks(node, 'citation')

    def before_table(self, node):

        # A table contains exactly one tgroup.  See before_tgroup.

        pass

    def before_tgroup(self, node):