Source

scikits_index / code / docutils / writers / newlatex2e / __init__.py

Full commit
Janto Dreijer 0da80a7 


































































































































































































































































































































































































































































































































































































































































































































































































































































  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
# $Id: __init__.py 5738 2008-11-30 08:59:04Z grubert $
# 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

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)

        lang = self.settings.language_code or ''
        if lang.startswith('de'):
            self.double_quote_replacment = "{\\dq}"
        elif lang.startswith('it'):
            self.double_quote_replacment = r'{\char`\"}'
        else:
            self.double_quote_replacment = None

        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}')
            if self.double_quote_replacment is not None:
                text = text.replace('"', self.double_quote_replacment)

            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):
        widths = []
        total_width = 0
        for i in range(int(node['cols'])):
            assert isinstance(node[i], nodes.colspec)
            widths.append(int(node[i]['colwidth']) + 1)
            total_width += widths[-1]
        del node[:len(widths)]
        tablespec = '|'
        for w in widths:
            # 0.93 is probably wrong in many cases.  XXX Find a
            # solution which works *always*.
            tablespec += r'p{%s\textwidth}|' % (0.93 * w /
                                                max(total_width, 60))
        self.append(r'\DECmaketable{%s}{' % tablespec)
        self.context.append('}')
        raise SkipAttrParentLaTeX

    def depart_tgroup(self, node):
        self.append(self.context.pop())

    def before_row(self, node):
        raise SkipAttrParentLaTeX

    def before_thead(self, node):
        raise SkipAttrParentLaTeX

    def before_tbody(self, node):
        raise SkipAttrParentLaTeX

    def is_simply_entry(self, node):
        return (len(node) == 1 and isinstance(node[0], nodes.paragraph) or
                len(node) == 0)

    def before_entry(self, node):
        is_leftmost = 0
        if node.hasattr('morerows'):
            self.document.reporter.severe('Rowspans are not supported.')
            # Todo: Add empty cells below rowspanning cell and issue
            # warning instead of severe.
        if node.hasattr('morecols'):
            # The author got a headache trying to implement
            # multicolumn support.
            if not self.is_simply_entry(node):
                self.document.reporter.severe(
                    'Colspanning table cells may only contain one paragraph.')
                # Todo: Same as above.
            # The number of columns this entry spans (as a string).
            colspan = int(node['morecols']) + 1
            del node['morecols']
        else:
            colspan = 1
        # Macro to call -- \DECcolspan or \DECcolspanleft.
        macro_name = r'\DECcolspan'
        if node.parent.index(node) == 0:
            # Leftmost column.
            macro_name += 'left'
            is_leftmost = 1
        if colspan > 1:
            self.append('%s{%s}{' % (macro_name, colspan))
            self.context.append('}')
        else:
            # Do not add a multicolumn with colspan 1 beacuse we need
            # at least one non-multicolumn cell per column to get the
            # desired column widths, and we can only do colspans with
            # cells consisting of only one paragraph.
            if not is_leftmost:
                self.append(r'\DECsubsequententry{')
                self.context.append('}')
            else:
                self.context.append('')
        if isinstance(node.parent.parent, nodes.thead):
            node['tableheaderentry'] = 'true'

        # Don't add \renewcommand{\DEVparent}{...} because there must
        # not be any non-expandable commands in front of \multicolumn.
        raise SkipParentLaTeX

    def depart_entry(self, node):
        self.append(self.context.pop())

    def before_substitution_definition(self, node):
        raise nodes.SkipNode

    indentation_level = 0

    def node_name(self, node):
        return node.__class__.__name__.replace('_', '')

    # Attribute propagation order.
    attribute_order = ['align', 'classes', 'ids']

    def attribute_cmp(self, a1, a2):
        """
        Compare attribute names `a1` and `a2`.  Used in
        propagate_attributes to determine propagation order.

        See built-in function `cmp` for return value.
        """
        if a1 in self.attribute_order and a2 in self.attribute_order:
            return cmp(self.attribute_order.index(a1),
                       self.attribute_order.index(a2))
        if (a1 in self.attribute_order) != (a2 in self.attribute_order):
            # Attributes not in self.attribute_order come last.
            return a1 in self.attribute_order and -1 or 1
        else:
            return cmp(a1, a2)

    def propagate_attributes(self, node):
        # Propagate attributes using \DECattr macros.
        node_name = self.node_name(node)
        attlist = []
        if isinstance(node, nodes.Element):
            attlist = node.attlist()
        attlist.sort(lambda pair1, pair2: self.attribute_cmp(pair1[0],
                                                             pair2[0]))
        # `numatts` may be greater than len(attlist) due to list
        # attributes.
        numatts = 0
        pass_contents = self.pass_contents(node)
        for key, value in attlist:
            if isinstance(value, list):
                self.append(r'\renewcommand{\DEVattrlen}{%s}' % len(value))
                for i in range(len(value)):
                    self.append(r'\DECattr{%s}{%s}{%s}{%s}{' %
                                (i+1, key, self.encode(value[i], attval=key),
                                 node_name))
                    if not pass_contents:
                        self.append('}')
                numatts += len(value)
            else:
                self.append(r'\DECattr{}{%s}{%s}{%s}{' %
                            (key, self.encode(unicode(value), attval=key),
                             node_name))
                if not pass_contents:
                    self.append('}')
                numatts += 1
        if pass_contents:
            self.context.append('}' * numatts)  # for Emacs: {
        else:
            self.context.append('')

    def visit_docinfo(self, node):
        raise NotImplementedError('Docinfo not yet implemented.')

    def visit_document(self, node):
        document = node
        # Move IDs into TextElements.  This won't work for images.
        # Need to review this.
        for node in document.traverse(nodes.Element):
            if 'ids' in node and not isinstance(node,
                                                      nodes.TextElement):
                next_text_element = node.next_node(nodes.TextElement)
                if next_text_element:
                    next_text_element['ids'].extend(node['ids'])
                    node['ids'] = []

    def pass_contents(self, node):
        r"""
        Return True if the node contents should be passed in
        \DN<nodename>{<contents>} and \DECattr{}{}{}{}{<contents>}.
        Return False if the node contents should be passed in
        \DECvisit<nodename> <contents> \DECdepart<nodename>, and no
        attribute handler should be called.
        """
        # Passing the whole document or whole sections as parameters
        # to \DN... or \DECattr causes LaTeX to run out of memory.
        return not isinstance(node, (nodes.document, nodes.section))

    def dispatch_visit(self, node):
        skip_attr = skip_parent = 0
        # TreePruningException to be propagated.
        tree_pruning_exception = None
        if hasattr(self, 'before_' + node.__class__.__name__):
            try:
                getattr(self, 'before_' + node.__class__.__name__)(node)
            except SkipParentLaTeX:
                skip_parent = 1
            except SkipAttrParentLaTeX:
                skip_attr = 1
                skip_parent = 1
            except nodes.SkipNode:
                raise
            except (nodes.SkipChildren, nodes.SkipSiblings), instance:
                tree_pruning_exception = instance
            except nodes.SkipDeparture:
                raise NotImplementedError(
                    'SkipDeparture not usable in LaTeX writer')

        if not isinstance(node, nodes.Text):
            node_name = self.node_name(node)
            # attribute_deleters will be appended to self.context.
            attribute_deleters = []
            if not skip_parent and not isinstance(node, nodes.document):
                self.append(r'\renewcommand{\DEVparent}{%s}'
                            % self.node_name(node.parent))
                for name, value in node.attlist():
                    if not isinstance(value, list) and not ':' in name:
                        # For non-list and non-special (like
                        # 'xml:preserve') attributes, set
                        # \DEVcurrentN<nodename>A<attribute> to the
                        # attribute value, so that the value of the
                        # attribute is available in the node handler
                        # and all children.
                        macro = r'\DEVcurrentN%sA%s' % (node_name, name)
                        self.append(r'\def%s{%s}' % (
                            macro, self.encode(unicode(value), attval=name)))
                        # Make the attribute undefined afterwards.
                        attribute_deleters.append(r'\let%s=\relax' % macro)
            self.context.append('\n'.join(attribute_deleters))
            if self.pass_contents(node):
                # Call \DN<nodename>{<contents>}.
                self.append(r'\DN%s{' % node_name)
                self.context.append('}')
            else:
                # Call \DECvisit<nodename> <contents>
                # \DECdepart<nodename>.  (Maybe we should use LaTeX
                # environments for this?)
                self.append(r'\DECvisit%s' % node_name)
                self.context.append(r'\DECdepart%s' % node_name)
            self.indentation_level += 1
            if not skip_attr:
                self.propagate_attributes(node)
            else:
                self.context.append('')

        if (isinstance(node, nodes.TextElement) and
            not isinstance(node.parent, nodes.TextElement)):
            # Reset current quote to left.
            self.left_quote = 1

        # Call visit_... method.
        try:
            nodes.SparseNodeVisitor.dispatch_visit(self, node)
        except LaTeXException:
            raise NotImplementedError(
                'visit_... methods must not raise LaTeXExceptions')

        if tree_pruning_exception:
            # Propagate TreePruningException raised in before_... method.
            raise tree_pruning_exception

    def is_invisible(self, node):
        # Return true if node is invisible or moved away in the LaTeX
        # rendering.
        return (not isinstance(node, nodes.Text) and
                (isinstance(node, nodes.Invisible) or
                 isinstance(node, nodes.footnote) or
                 isinstance(node, nodes.citation) or
                 # Assume raw nodes to be invisible.
                 isinstance(node, nodes.raw) or
                 # Floating image or figure.
                 node.get('align') in ('left', 'right')))

    def is_visible(self, node):
        return not self.is_invisible(node)

    def needs_space(self, node):
        """Two nodes for which `needs_space` is true need auxiliary space."""
        # Return true if node is a visible block-level element.
        return ((isinstance(node, nodes.Body) or
                 isinstance(node, nodes.topic)) and
                not (self.is_invisible(node) or
                     isinstance(node.parent, nodes.TextElement)))

    def always_needs_space(self, node):
        """
        Always add space around nodes for which `always_needs_space()`
        is true, regardless of whether the other node needs space as
        well.  (E.g. transition next to section.)
        """
        return isinstance(node, nodes.transition)

    def dispatch_departure(self, node):
        # Call departure method.
        nodes.SparseNodeVisitor.dispatch_departure(self, node)

        if not isinstance(node, nodes.Text):
            # Close attribute and node handler call (\DN...{...}).
            self.indentation_level -= 1
            self.append(self.context.pop() + self.context.pop())
            # Delete \DECcurrentN... attribute macros.
            self.append(self.context.pop())
            # Get next sibling.
            next_node = node.next_node(
                ascend=0, siblings=1, descend=0,
                condition=self.is_visible)
            # Insert space if necessary.
            if  (self.needs_space(node) and self.needs_space(next_node) or
                 self.always_needs_space(node) or
                 self.always_needs_space(next_node)):
                if isinstance(node, nodes.paragraph) and isinstance(next_node, nodes.paragraph):
                    # Space between paragraphs.
                    self.append(r'\DECparagraphspace')
                else:
                    # One of the elements is not a paragraph.
                    self.append(r'\DECauxiliaryspace')