1 # $Id: __init__.py 5333 2007-07-10 17:31:28Z grubert $

     2 # Author: Engelbert Gruber <grubert@users.sourceforge.net>

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

     4 

     5 """

     6 LaTeX2e document tree Writer.

     7 """

     8 

     9 __docformat__ = 'reStructuredText'

    10 

    11 # code contributions from several people included, thanks to all.

    12 # some named: David Abrahams, Julien Letessier, Lele Gaifax, and others.

    13 #

    14 # convention deactivate code by two # e.g. ##.

    15 

    16 import sys

    17 import time

    18 import re

    19 import string

    20 from types import ListType

    21 from docutils import frontend, nodes, languages, writers, utils

    22 from docutils.writers.newlatex2e import unicode_map

    23 

    24 from docutils.transforms.references import DanglingReferencesVisitor

    25 

    26 class Writer(writers.Writer):

    27 

    28     supported = ('latex','latex2e')

    29     """Formats this writer supports."""

    30 

    31     settings_spec = (

    32         'LaTeX-Specific Options',

    33         'The LaTeX "--output-encoding" default is "latin-1:strict".',

    34         (('Specify documentclass.  Default is "article".',

    35           ['--documentclass'],

    36           {'default': 'article', }),

    37          ('Specify document options.  Multiple options can be given, '

    38           'separated by commas.  Default is "10pt,a4paper".',

    39           ['--documentoptions'],

    40           {'default': '10pt,a4paper', }),

    41          ('Use LaTeX footnotes. LaTeX supports only numbered footnotes (does it?). '

    42           'Default: no, uses figures.',

    43           ['--use-latex-footnotes'],

    44           {'default': 0, 'action': 'store_true',

    45            'validator': frontend.validate_boolean}),

    46          ('Format for footnote references: one of "superscript" or '

    47           '"brackets".  Default is "superscript".',

    48           ['--footnote-references'],

    49           {'choices': ['superscript', 'brackets'], 'default': 'superscript',

    50            'metavar': '<format>',

    51            'overrides': 'trim_footnote_reference_space'}),

    52          ('Use LaTeX citations. '

    53           'Default: no, uses figures which might get mixed with images.',

    54           ['--use-latex-citations'],

    55           {'default': 0, 'action': 'store_true',

    56            'validator': frontend.validate_boolean}),

    57          ('Format for block quote attributions: one of "dash" (em-dash '

    58           'prefix), "parentheses"/"parens", or "none".  Default is "dash".',

    59           ['--attribution'],

    60           {'choices': ['dash', 'parentheses', 'parens', 'none'],

    61            'default': 'dash', 'metavar': '<format>'}),

    62          ('Specify a stylesheet file. The file will be "input" by latex in '

    63           'the document header.  Default is no stylesheet ("").  '

    64           'Overrides --stylesheet-path.',

    65           ['--stylesheet'],

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

    67            'overrides': 'stylesheet_path'}),

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

    69           'directory.  Overrides --stylesheet.',

    70           ['--stylesheet-path'],

    71           {'metavar': '<file>', 'overrides': 'stylesheet'}),

    72          ('Table of contents by docutils (default) or LaTeX. LaTeX (writer) '

    73           'supports only one ToC per document, but docutils does not know of '

    74           'pagenumbers. LaTeX table of contents also means LaTeX generates '

    75           'sectionnumbers.',

    76           ['--use-latex-toc'],

    77           {'default': 0, 'action': 'store_true',

    78            'validator': frontend.validate_boolean}),

    79          ('Add parts on top of the section hierarchy.',

    80           ['--use-part-section'],

    81           {'default': 0, 'action': 'store_true',

    82            'validator': frontend.validate_boolean}),

    83          ('Let LaTeX print author and date, do not show it in docutils '

    84           'document info.',

    85           ['--use-latex-docinfo'],

    86           {'default': 0, 'action': 'store_true',

    87            'validator': frontend.validate_boolean}),

    88          ('Use LaTeX abstract environment for the documents abstract.'

    89           'Per default the abstract is an unnumbered section.',

    90           ['--use-latex-abstract'],

    91           {'default': 0, 'action': 'store_true',

    92            'validator': frontend.validate_boolean}),

    93          ('Color of any hyperlinks embedded in text '

    94           '(default: "blue", "0" to disable).',

    95           ['--hyperlink-color'], {'default': 'blue'}),

    96          ('Enable compound enumerators for nested enumerated lists '

    97           '(e.g. "1.2.a.ii").  Default: disabled.',

    98           ['--compound-enumerators'],

    99           {'default': None, 'action': 'store_true',

   100            'validator': frontend.validate_boolean}),

   101          ('Disable compound enumerators for nested enumerated lists.  This is '

   102           'the default.',

   103           ['--no-compound-enumerators'],

   104           {'action': 'store_false', 'dest': 'compound_enumerators'}),

   105          ('Enable section ("." subsection ...) prefixes for compound '

   106           'enumerators.  This has no effect without --compound-enumerators.  '

   107           'Default: disabled.',

   108           ['--section-prefix-for-enumerators'],

   109           {'default': None, 'action': 'store_true',

   110            'validator': frontend.validate_boolean}),

   111          ('Disable section prefixes for compound enumerators.  '

   112           'This is the default.',

   113           ['--no-section-prefix-for-enumerators'],

   114           {'action': 'store_false', 'dest': 'section_prefix_for_enumerators'}),

   115          ('Set the separator between section number and enumerator '

   116           'for compound enumerated lists.  Default is "-".',

   117           ['--section-enumerator-separator'],

   118           {'default': '-', 'metavar': '<char>'}),

   119          ('When possibile, use verbatim for literal-blocks. '

   120           'Default is to always use the mbox environment.',

   121           ['--use-verbatim-when-possible'],

   122           {'default': 0, 'action': 'store_true',

   123            'validator': frontend.validate_boolean}),

   124          ('Table style. "standard" with horizontal and vertical lines, '

   125           '"booktabs" (LaTeX booktabs style) only horizontal lines '

   126           'above and below the table and below the header or "nolines".  '

   127           'Default: "standard"',

   128           ['--table-style'],

   129           {'choices': ['standard', 'booktabs','nolines'], 'default': 'standard',

   130            'metavar': '<format>'}),

   131          ('LaTeX graphicx package option. '

   132           'Possible values are "dvips", "pdftex". "auto" includes LaTeX code '

   133           'to use "pdftex" if processing with pdf(la)tex and dvips otherwise. '

   134           'Default is no option.',

   135           ['--graphicx-option'],

   136           {'default': ''}),

   137          ('LaTeX font encoding. '

   138           'Possible values are "T1", "OT1", "" or some other fontenc option. '

   139           'The font encoding influences available symbols, e.g. "<<" as one '

   140           'character. Default is "" which leads to package "ae" (a T1 '

   141           'emulation using CM fonts).',

   142           ['--font-encoding'],

   143           {'default': ''}),

   144          ('Per default the latex-writer puts the reference title into '

   145           'hyperreferences. Specify "ref*" or "pageref*" to get the section '

   146           'number or the page number.',

   147           ['--reference-label'],

   148           {'default': None, }),

   149          ('Specify style and database for bibtex, for example '

   150           '"--use-bibtex=mystyle,mydb1,mydb2".',

   151           ['--use-bibtex'],

   152           {'default': None, }),

   153           ),)

   154 

   155     settings_defaults = {'output_encoding': 'latin-1'}

   156 

   157     relative_path_settings = ('stylesheet_path',)

   158 

   159     config_section = 'latex2e writer'

   160     config_section_dependencies = ('writers',)

   161 

   162     visitor_attributes = ("head_prefix", "head", 

   163             "body_prefix", "body", "body_suffix")

   164 

   165     output = None

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

   167 

   168     def __init__(self):

   169         writers.Writer.__init__(self)

   170         self.translator_class = LaTeXTranslator

   171 

   172     def translate(self):

   173         visitor = self.translator_class(self.document)

   174         self.document.walkabout(visitor)

   175         self.output = visitor.astext()

   176         # copy parts 

   177         for attr in self.visitor_attributes:

   178             setattr(self, attr, getattr(visitor, attr))

   179 

   180     def assemble_parts(self):

   181         writers.Writer.assemble_parts(self)

   182         for part in self.visitor_attributes:

   183             self.parts[part] = ''.join(getattr(self, part))

   184 

   185 

   186 """

   187 Notes on LaTeX

   188 --------------

   189 

   190 * LaTeX does not support multiple tocs in one document.

   191   (might be no limitation except for docutils documentation)

   192 

   193   The "minitoc" latex package can produce per-chapter tocs in

   194   book and report document classes.

   195 

   196 * width

   197 

   198   * linewidth - width of a line in the local environment

   199   * textwidth - the width of text on the page

   200 

   201   Maybe always use linewidth ?

   202 

   203   *Bug* inside a minipage a (e.g. Sidebar) the linewidth is

   204         not changed, needs fix in docutils so that tables

   205         are not too wide.

   206 

   207         So we add locallinewidth set it initially and

   208         on entering sidebar and reset on exit.

   209 """

   210 

   211 class Babel:

   212     """Language specifics for LaTeX."""

   213     # country code by a.schlock.

   214     # partly manually converted from iso and babel stuff, dialects and some

   215     _ISO639_TO_BABEL = {

   216         'no': 'norsk',     #XXX added by hand ( forget about nynorsk?)

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

   218         'hu': 'magyar',    #XXX added by hand

   219         'pt': 'portuguese',#XXX added by hand

   220         'sl': 'slovenian',

   221         'af': 'afrikaans',

   222         'bg': 'bulgarian',

   223         'br': 'breton',

   224         'ca': 'catalan',

   225         'cs': 'czech',

   226         'cy': 'welsh',

   227         'da': 'danish',

   228         'fr': 'french',

   229         # french, francais, canadien, acadian

   230         'de': 'ngerman',  #XXX rather than german

   231         # ngerman, naustrian, german, germanb, austrian

   232         'el': 'greek',

   233         'en': 'english',

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

   235         'eo': 'esperanto',

   236         'es': 'spanish',

   237         'et': 'estonian',

   238         'eu': 'basque',

   239         'fi': 'finnish',

   240         'ga': 'irish',

   241         'gl': 'galician',

   242         'he': 'hebrew',

   243         'hr': 'croatian',

   244         'hu': 'hungarian',

   245         'is': 'icelandic',

   246         'it': 'italian',

   247         'la': 'latin',

   248         'nl': 'dutch',

   249         'pl': 'polish',

   250         'pt': 'portuguese',

   251         'ro': 'romanian',

   252         'ru': 'russian',

   253         'sk': 'slovak',

   254         'sr': 'serbian',

   255         'sv': 'swedish',

   256         'tr': 'turkish',

   257         'uk': 'ukrainian'

   258     }

   259 

   260     def __init__(self,lang):

   261         self.language = lang

   262         # pdflatex does not produce double quotes for ngerman in tt.

   263         self.double_quote_replacment = None

   264         if re.search('^de',self.language):

   265             #self.quotes = ("\"`", "\"'")

   266             self.quotes = ('{\\glqq}', '{\\grqq}')

   267             self.double_quote_replacment = "{\\dq}"

   268         elif re.search('^it',self.language):

   269             self.quotes = ("``", "''")

   270             self.double_quote_replacment = r'{\char`\"}'

   271         else:

   272             self.quotes = ("``", "''")

   273         self.quote_index = 0

   274 

   275     def next_quote(self):

   276         q = self.quotes[self.quote_index]

   277         self.quote_index = (self.quote_index+1)%2

   278         return q

   279 

   280     def quote_quotes(self,text):

   281         t = None

   282         for part in text.split('"'):

   283             if t == None:

   284                 t = part

   285             else:

   286                 t += self.next_quote() + part

   287         return t

   288 

   289     def double_quotes_in_tt (self,text):

   290         if not self.double_quote_replacment:

   291             return text

   292         return text.replace('"', self.double_quote_replacment)

   293 

   294     def get_language(self):

   295         if self._ISO639_TO_BABEL.has_key(self.language):

   296             return self._ISO639_TO_BABEL[self.language]

   297         else:

   298             # support dialects.

   299             l = self.language.split("_")[0]

   300             if self._ISO639_TO_BABEL.has_key(l):

   301                 return self._ISO639_TO_BABEL[l]

   302         return None

   303 

   304 

   305 latex_headings = {

   306         'optionlist_environment' : [

   307               '\\newcommand{\\optionlistlabel}[1]{\\bf #1 \\hfill}\n'

   308               '\\newenvironment{optionlist}[1]\n'

   309               '{\\begin{list}{}\n'

   310               '  {\\setlength{\\labelwidth}{#1}\n'

   311               '   \\setlength{\\rightmargin}{1cm}\n'

   312               '   \\setlength{\\leftmargin}{\\rightmargin}\n'

   313               '   \\addtolength{\\leftmargin}{\\labelwidth}\n'

   314               '   \\addtolength{\\leftmargin}{\\labelsep}\n'

   315               '   \\renewcommand{\\makelabel}{\\optionlistlabel}}\n'

   316               '}{\\end{list}}\n',

   317               ],

   318         'lineblock_environment' : [

   319             '\\newlength{\\lineblockindentation}\n'

   320             '\\setlength{\\lineblockindentation}{2.5em}\n'

   321             '\\newenvironment{lineblock}[1]\n'

   322             '{\\begin{list}{}\n'

   323             '  {\\setlength{\\partopsep}{\\parskip}\n'

   324             '   \\addtolength{\\partopsep}{\\baselineskip}\n'

   325             '   \\topsep0pt\\itemsep0.15\\baselineskip\\parsep0pt\n'

   326             '   \\leftmargin#1}\n'

   327             ' \\raggedright}\n'

   328             '{\\end{list}}\n'

   329             ],

   330         'footnote_floats' : [

   331             '% begin: floats for footnotes tweaking.\n',

   332             '\\setlength{\\floatsep}{0.5em}\n',

   333             '\\setlength{\\textfloatsep}{\\fill}\n',

   334             '\\addtolength{\\textfloatsep}{3em}\n',

   335             '\\renewcommand{\\textfraction}{0.5}\n',

   336             '\\renewcommand{\\topfraction}{0.5}\n',

   337             '\\renewcommand{\\bottomfraction}{0.5}\n',

   338             '\\setcounter{totalnumber}{50}\n',

   339             '\\setcounter{topnumber}{50}\n',

   340             '\\setcounter{bottomnumber}{50}\n',

   341             '% end floats for footnotes\n',

   342             ],

   343         'some_commands' : [

   344             '% some commands, that could be overwritten in the style file.\n'

   345             '\\newcommand{\\rubric}[1]'

   346             '{\\subsection*{~\\hfill {\\it #1} \\hfill ~}}\n'

   347             '\\newcommand{\\titlereference}[1]{\\textsl{#1}}\n'

   348             '% end of "some commands"\n',

   349             ]

   350         }

   351 

   352 class DocumentClass:

   353     """Details of a LaTeX document class."""

   354 

   355     def __init__(self, document_class, with_part=False):

   356         self.document_class = document_class

   357         self._with_part = with_part

   358 

   359     def section(self, level):

   360         """ Return the section name at the given level for the specific

   361             document class.

   362 

   363             Level is 1,2,3..., as level 0 is the title."""

   364 

   365         sections = [ 'section', 'subsection', 'subsubsection', 

   366                      'paragraph', 'subparagraph' ]

   367         if self.document_class in ('book', 'report', 'scrreprt', 'scrbook'):

   368             sections.insert(0, 'chapter')

   369         if self._with_part:

   370             sections.insert(0, 'part')

   371         if level <= len(sections):

   372             return sections[level-1]

   373         else:

   374             return sections[-1]

   375 

   376 class Table:

   377     """ Manage a table while traversing.

   378         Maybe change to a mixin defining the visit/departs, but then

   379         class Table internal variables are in the Translator.

   380 

   381         Table style might be 

   382         

   383         * standard: horizontal and vertical lines

   384         * booktabs (requires booktabs latex package): only horizontal lines

   385         * nolines, borderless : no lines

   386     """

   387     def __init__(self,latex_type,table_style):

   388         self._latex_type = latex_type

   389         self._table_style = table_style

   390         self._open = 0

   391         # miscellaneous attributes

   392         self._attrs = {}

   393         self._col_width = []

   394         self._rowspan = []

   395         self.stubs = []

   396 

   397     def open(self):

   398         self._open = 1

   399         self._col_specs = []

   400         self.caption = None

   401         self._attrs = {}

   402         self._in_head = 0 # maybe context with search

   403     def close(self):

   404         self._open = 0

   405         self._col_specs = None

   406         self.caption = None

   407         self._attrs = {}

   408         self.stubs = []

   409     def is_open(self):

   410         return self._open

   411 

   412     def set_table_style(self, table_style):

   413         if not table_style in ('standard','booktabs','borderless','nolines'):

   414             return

   415         self._table_style = table_style

   416 

   417     def used_packages(self):

   418         if self._table_style == 'booktabs':

   419             return '\\usepackage{booktabs}\n'

   420         return ''

   421     def get_latex_type(self):

   422         return self._latex_type

   423 

   424     def set(self,attr,value):

   425         self._attrs[attr] = value

   426     def get(self,attr):

   427         if self._attrs.has_key(attr):

   428             return self._attrs[attr]

   429         return None

   430     def get_vertical_bar(self):

   431         if self._table_style == 'standard':

   432             return '|'

   433         return ''

   434     # horizontal lines are drawn below a row, because we.

   435     def get_opening(self):

   436         if self._latex_type == 'longtable':

   437             # otherwise longtable might move before paragraph and subparagraph

   438             prefix = '\\leavevmode\n'

   439         else:

   440             prefix = ''

   441         return '%s\\begin{%s}[c]' % (prefix, self._latex_type)

   442     def get_closing(self):

   443         line = ""

   444         if self._table_style == 'booktabs':

   445             line = '\\bottomrule\n'

   446         elif self._table_style == 'standard':

   447             lines = '\\hline\n'

   448         return '%s\\end{%s}' % (line,self._latex_type)

   449 

   450     def visit_colspec(self, node):

   451         self._col_specs.append(node)

   452         # "stubs" list is an attribute of the tgroup element:

   453         self.stubs.append(node.attributes.get('stub'))

   454 

   455     def get_colspecs(self):

   456         """

   457         Return column specification for longtable.

   458 

   459         Assumes reST line length being 80 characters.

   460         Table width is hairy.

   461 

   462         === ===

   463         ABC DEF

   464         === ===

   465 

   466         usually gets to narrow, therefore we add 1 (fiddlefactor).

   467         """

   468         width = 80

   469 

   470         total_width = 0.0

   471         # first see if we get too wide.

   472         for node in self._col_specs:

   473             colwidth = float(node['colwidth']+1) / width

   474             total_width += colwidth

   475         self._col_width = []

   476         self._rowspan = []

   477         # donot make it full linewidth

   478         factor = 0.93

   479         if total_width > 1.0:

   480             factor /= total_width

   481         bar = self.get_vertical_bar()

   482         latex_table_spec = ""

   483         for node in self._col_specs:

   484             colwidth = factor * float(node['colwidth']+1) / width

   485             self._col_width.append(colwidth+0.005)

   486             self._rowspan.append(0)

   487             latex_table_spec += "%sp{%.3f\\locallinewidth}" % (bar,colwidth+0.005)

   488         return latex_table_spec+bar

   489 

   490     def get_column_width(self):

   491         """ return columnwidth for current cell (not multicell)

   492         """

   493         return "%.2f\\locallinewidth" % self._col_width[self._cell_in_row-1]

   494 

   495     def visit_thead(self):

   496         self._in_thead = 1

   497         if self._table_style == 'standard':

   498             return ['\\hline\n']

   499         elif self._table_style == 'booktabs':

   500             return ['\\toprule\n']

   501         return []

   502     def depart_thead(self):

   503         a = []

   504         #if self._table_style == 'standard':

   505         #    a.append('\\hline\n')

   506         if self._table_style == 'booktabs':

   507             a.append('\\midrule\n')

   508         if self._latex_type == 'longtable':

   509             a.append('\\endhead\n')

   510         # for longtable one could add firsthead, foot and lastfoot

   511         self._in_thead = 0

   512         return a

   513     def visit_row(self):

   514         self._cell_in_row = 0

   515     def depart_row(self):

   516         res = [' \\\\\n']

   517         self._cell_in_row = None  # remove cell counter

   518         for i in range(len(self._rowspan)):

   519             if (self._rowspan[i]>0):

   520                 self._rowspan[i] -= 1

   521 

   522         if self._table_style == 'standard':

   523             rowspans = []

   524             for i in range(len(self._rowspan)):

   525                 if (self._rowspan[i]<=0):

   526                     rowspans.append(i+1)

   527             if len(rowspans)==len(self._rowspan):

   528                 res.append('\\hline\n')

   529             else:

   530                 cline = ''

   531                 rowspans.reverse()

   532                 # TODO merge clines

   533                 while 1:

   534                     try:

   535                         c_start = rowspans.pop()

   536                     except:

   537                         break

   538                     cline += '\\cline{%d-%d}\n' % (c_start,c_start)

   539                 res.append(cline)

   540         return res

   541 

   542     def set_rowspan(self,cell,value):

   543         try:

   544             self._rowspan[cell] = value

   545         except:

   546             pass

   547     def get_rowspan(self,cell):

   548         try:

   549             return self._rowspan[cell]

   550         except:

   551             return 0

   552     def get_entry_number(self):

   553         return self._cell_in_row

   554     def visit_entry(self):

   555         self._cell_in_row += 1

   556     def is_stub_column(self):

   557         if len(self.stubs) >= self._cell_in_row:

   558             return self.stubs[self._cell_in_row-1]

   559         return False

   560 

   561 

   562 class LaTeXTranslator(nodes.NodeVisitor):

   563 

   564     # When options are given to the documentclass, latex will pass them

   565     # to other packages, as done with babel.

   566     # Dummy settings might be taken from document settings

   567     

   568     # Templates

   569     # ---------

   570     

   571     latex_head = '\\documentclass[%s]{%s}\n'

   572     linking = '\\usepackage[colorlinks=%s,linkcolor=%s,urlcolor=%s]{hyperref}\n'

   573     stylesheet = '\\input{%s}\n'

   574     # add a generated on day , machine by user using docutils version.

   575     generator = '% generated by Docutils <http://docutils.sourceforge.net/>\n'

   576     # Config setting defaults

   577     # -----------------------

   578 

   579     # use latex tableofcontents or let docutils do it.

   580     use_latex_toc = 0

   581 

   582     # TODO: use mixins for different implementations.

   583     # list environment for docinfo. else tabularx

   584     use_optionlist_for_docinfo = 0 # NOT YET IN USE

   585 

   586     # Use compound enumerations (1.A.1.)

   587     compound_enumerators = 0

   588 

   589     # If using compound enumerations, include section information.

   590     section_prefix_for_enumerators = 0

   591 

   592     # This is the character that separates the section ("." subsection ...)

   593     # prefix from the regular list enumerator.

   594     section_enumerator_separator = '-'

   595 

   596     # default link color

   597     hyperlink_color = "blue"

   598 

   599     def __init__(self, document):

   600         nodes.NodeVisitor.__init__(self, document)

   601         self.settings = settings = document.settings

   602         self.latex_encoding = self.to_latex_encoding(settings.output_encoding)

   603         self.use_latex_toc = settings.use_latex_toc

   604         self.use_latex_docinfo = settings.use_latex_docinfo

   605         self.use_latex_footnotes = settings.use_latex_footnotes

   606         self._use_latex_citations = settings.use_latex_citations

   607         self._reference_label = settings.reference_label

   608         self.hyperlink_color = settings.hyperlink_color

   609         self.compound_enumerators = settings.compound_enumerators

   610         self.font_encoding = settings.font_encoding

   611         self.section_prefix_for_enumerators = (

   612             settings.section_prefix_for_enumerators)

   613         self.section_enumerator_separator = (

   614             settings.section_enumerator_separator.replace('_', '\\_'))

   615         if self.hyperlink_color == '0':

   616             self.hyperlink_color = 'black'

   617             self.colorlinks = 'false'

   618         else:

   619             self.colorlinks = 'true'

   620 

   621         if self.settings.use_bibtex:

   622             self.bibtex = self.settings.use_bibtex.split(",",1)

   623             # TODO avoid errors on not declared citations.

   624         else:

   625             self.bibtex = None

   626         # language: labels, bibliographic_fields, and author_separators.

   627         # to allow writing labes for specific languages.

   628         self.language = languages.get_language(settings.language_code)

   629         self.babel = Babel(settings.language_code)

   630         self.author_separator = self.language.author_separators[0]

   631         self.d_options = self.settings.documentoptions

   632         if self.babel.get_language():

   633             self.d_options += ',%s' % self.babel.get_language()

   634 

   635         self.d_class = DocumentClass(settings.documentclass, 

   636                                      settings.use_part_section)

   637         # object for a table while proccessing.

   638         self.table_stack = []

   639         self.active_table = Table('longtable',settings.table_style)

   640 

   641         # HACK.  Should have more sophisticated typearea handling.

   642         if settings.documentclass.find('scr') == -1:

   643             self.typearea = '\\usepackage[DIV12]{typearea}\n'

   644         else:

   645             if self.d_options.find('DIV') == -1 and self.d_options.find('BCOR') == -1:

   646                 self.typearea = '\\typearea{12}\n'

   647             else:

   648                 self.typearea = ''

   649 

   650         if self.font_encoding == 'OT1':

   651             fontenc_header = ''

   652         elif self.font_encoding == '':

   653             fontenc_header = '\\usepackage{ae}\n\\usepackage{aeguill}\n'

   654         else:

   655             fontenc_header = '\\usepackage[%s]{fontenc}\n' % (self.font_encoding,)

   656         if self.latex_encoding.startswith('utf8'):

   657             input_encoding = '\\usepackage{ucs}\n\\usepackage[utf8x]{inputenc}\n'

   658         else:

   659             input_encoding = '\\usepackage[%s]{inputenc}\n' % self.latex_encoding

   660         if self.settings.graphicx_option == '':

   661             self.graphicx_package = '\\usepackage{graphicx}\n'

   662         elif self.settings.graphicx_option.lower() == 'auto':

   663             self.graphicx_package = '\n'.join(

   664                 ('%Check if we are compiling under latex or pdflatex',

   665                  '\\ifx\\pdftexversion\\undefined',

   666                  '  \\usepackage{graphicx}',

   667                  '\\else',

   668                  '  \\usepackage[pdftex]{graphicx}',

   669                  '\\fi\n'))

   670         else:

   671             self.graphicx_package = (

   672                 '\\usepackage[%s]{graphicx}\n' % self.settings.graphicx_option)

   673 

   674         self.head_prefix = [

   675               self.latex_head % (self.d_options,self.settings.documentclass),

   676               '\\usepackage{babel}\n',     # language is in documents settings.

   677               fontenc_header,

   678               '\\usepackage{shortvrb}\n',  # allows verb in footnotes.

   679               input_encoding,

   680               # * tabularx: for docinfo, automatic width of columns, always on one page.

   681               '\\usepackage{tabularx}\n',

   682               '\\usepackage{longtable}\n',

   683               self.active_table.used_packages(),

   684               # possible other packages.

   685               # * fancyhdr

   686               # * ltxtable is a combination of tabularx and longtable (pagebreaks).

   687               #   but ??

   688               #

   689               # extra space between text in tables and the line above them

   690               '\\setlength{\\extrarowheight}{2pt}\n',

   691               '\\usepackage{amsmath}\n',   # what fore amsmath.

   692               self.graphicx_package,

   693               '\\usepackage{color}\n',

   694               '\\usepackage{multirow}\n',

   695               '\\usepackage{ifthen}\n',   # before hyperref!

   696               self.linking % (self.colorlinks, self.hyperlink_color, self.hyperlink_color),

   697               self.typearea,

   698               self.generator,

   699               # latex lengths

   700               '\\newlength{\\admonitionwidth}\n',

   701               '\\setlength{\\admonitionwidth}{0.9\\textwidth}\n'

   702               # width for docinfo tablewidth

   703               '\\newlength{\\docinfowidth}\n',

   704               '\\setlength{\\docinfowidth}{0.9\\textwidth}\n'

   705               # linewidth of current environment, so tables are not wider

   706               # than the sidebar: using locallinewidth seems to defer evaluation

   707               # of linewidth, this is fixing it.

   708               '\\newlength{\\locallinewidth}\n',

   709               # will be set later.

   710               ]

   711         self.head_prefix.extend( latex_headings['optionlist_environment'] )

   712         self.head_prefix.extend( latex_headings['lineblock_environment'] )

   713         self.head_prefix.extend( latex_headings['footnote_floats'] )

   714         self.head_prefix.extend( latex_headings['some_commands'] )

   715         ## stylesheet is last: so it might be possible to overwrite defaults.

   716         stylesheet = utils.get_stylesheet_reference(settings)

   717         if stylesheet:

   718             settings.record_dependencies.add(stylesheet)

   719             self.head_prefix.append(self.stylesheet % (stylesheet))

   720 

   721         if self.linking: # and maybe check for pdf

   722             self.pdfinfo = [ ]

   723             self.pdfauthor = None

   724             # pdftitle, pdfsubject, pdfauthor, pdfkeywords, 

   725             # pdfcreator, pdfproducer

   726         else:

   727             self.pdfinfo = None

   728         # NOTE: Latex wants a date and an author, rst puts this into

   729         #   docinfo, so normally we do not want latex author/date handling.

   730         # latex article has its own handling of date and author, deactivate.

   731         # self.astext() adds \title{...} \author{...} \date{...}, even if the

   732         # "..." are empty strings.

   733         self.head = [ ]

   734         # separate title, so we can appen subtitle.

   735         self.title = ''

   736         # if use_latex_docinfo: collects lists of author/organization/contact/address lines

   737         self.author_stack = []

   738         self.date = ''

   739 

   740         self.body_prefix = ['\\raggedbottom\n']

   741         self.body = []

   742         self.body_suffix = ['\n']

   743         self.section_level = 0

   744         self.context = []

   745         self.topic_classes = []

   746         # column specification for tables

   747         self.table_caption = None

   748         

   749         # Flags to encode

   750         # ---------------

   751         # verbatim: to tell encode not to encode.

   752         self.verbatim = 0

   753         # insert_newline: to tell encode to replace blanks by "~".

   754         self.insert_none_breaking_blanks = 0

   755         # insert_newline: to tell encode to add latex newline.

   756         self.insert_newline = 0

   757         # mbox_newline: to tell encode to add mbox and newline.

   758         self.mbox_newline = 0

   759         # inside citation reference labels underscores dont need to be escaped.

   760         self.inside_citation_reference_label = 0

   761 

   762         # Stack of section counters so that we don't have to use_latex_toc.

   763         # This will grow and shrink as processing occurs.

   764         # Initialized for potential first-level sections.

   765         self._section_number = [0]

   766 

   767         # The current stack of enumerations so that we can expand

   768         # them into a compound enumeration.  

   769         self._enumeration_counters = []

   770 

   771         # The maximum number of enumeration counters we've used.

   772         # If we go beyond this number, we need to create a new

   773         # counter; otherwise, just reuse an old one.

   774         self._max_enumeration_counters = 0

   775 

   776         self._bibitems = []

   777 

   778         # docinfo.

   779         self.docinfo = None

   780         # inside literal block: no quote mangling.

   781         self.literal_block = 0

   782         self.literal_block_stack = []

   783         self.literal = 0

   784         # true when encoding in math mode

   785         self.mathmode = 0

   786 

   787     def to_latex_encoding(self,docutils_encoding):

   788         """

   789         Translate docutils encoding name into latex's.

   790 

   791         Default fallback method is remove "-" and "_" chars from docutils_encoding.

   792 

   793         """

   794         tr = {  "iso-8859-1": "latin1",     # west european

   795                 "iso-8859-2": "latin2",     # east european

   796                 "iso-8859-3": "latin3",     # esperanto, maltese

   797                 "iso-8859-4": "latin4",     # north european,scandinavian, baltic

   798                 "iso-8859-5": "iso88595",   # cyrillic (ISO)

   799                 "iso-8859-9": "latin5",     # turkish

   800                 "iso-8859-15": "latin9",    # latin9, update to latin1.

   801                 "mac_cyrillic": "maccyr",   # cyrillic (on Mac)

   802                 "windows-1251": "cp1251",   # cyrillic (on Windows)

   803                 "koi8-r": "koi8-r",         # cyrillic (Russian)

   804                 "koi8-u": "koi8-u",         # cyrillic (Ukrainian)

   805                 "windows-1250": "cp1250",   #

   806                 "windows-1252": "cp1252",   #

   807                 "us-ascii": "ascii",        # ASCII (US)

   808                 # unmatched encodings

   809                 #"": "applemac",

   810                 #"": "ansinew",  # windows 3.1 ansi

   811                 #"": "ascii",    # ASCII encoding for the range 32--127.

   812                 #"": "cp437",    # dos latine us

   813                 #"": "cp850",    # dos latin 1

   814                 #"": "cp852",    # dos latin 2

   815                 #"": "decmulti",

   816                 #"": "latin10",

   817                 #"iso-8859-6": ""   # arabic

   818                 #"iso-8859-7": ""   # greek

   819                 #"iso-8859-8": ""   # hebrew

   820                 #"iso-8859-10": ""   # latin6, more complete iso-8859-4

   821              }

   822         if tr.has_key(docutils_encoding.lower()):

   823             return tr[docutils_encoding.lower()]

   824         # convert: latin-1 and utf-8 and similar things

   825         return docutils_encoding.replace("_", "").replace("-", "").lower()

   826 

   827     def language_label(self, docutil_label):

   828         return self.language.labels[docutil_label]

   829 

   830     latex_equivalents = {

   831         u'\u00A0' : '~',

   832         u'\u2013' : '{--}',

   833         u'\u2014' : '{---}',

   834         u'\u2018' : '`',

   835         u'\u2019' : '\'',

   836         u'\u201A' : ',',

   837         u'\u201C' : '``',

   838         u'\u201D' : '\'\'',

   839         u'\u201E' : ',,',

   840         u'\u2020' : '{\\dag}',

   841         u'\u2021' : '{\\ddag}',

   842         u'\u2026' : '{\\dots}',

   843         u'\u2122' : '{\\texttrademark}',

   844         u'\u21d4' : '{$\\Leftrightarrow$}',

   845         # greek alphabet ?

   846     }

   847 

   848     def unicode_to_latex(self,text):

   849         # see LaTeX codec

   850         # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252124

   851         # Only some special chracters are translated, for documents with many

   852         # utf-8 chars one should use the LaTeX unicode package.

   853         for uchar in self.latex_equivalents.keys():

   854             text = text.replace(uchar,self.latex_equivalents[uchar])

   855         return text

   856 

   857     def ensure_math(self, text):

   858         if not self.__dict__.has_key('ensure_math_re'):

   859             chars = {

   860                 # lnot,pm,twosuperior,threesuperior,mu,onesuperior,times,div

   861                 'latin1' : '\xac\xb1\xb2\xb3\xb5\xb9\xd7\xf7' ,

   862                 # also latin5 and latin9

   863                 }

   864             self.ensure_math_re = re.compile('([%s])' % chars['latin1'])

   865         text = self.ensure_math_re.sub(r'\\ensuremath{\1}', text)

   866         return text

   867 

   868     def encode(self, text):

   869         """

   870         Encode special characters (``# $ % & ~ _ ^ \ { }``) in `text` & return

   871         """

   872         # Escaping with a backslash does not help with backslashes, ~ and ^.

   873 

   874         #     < > are only available in math-mode or tt font. (really ?)

   875         #     $ starts math- mode.

   876         # AND quotes

   877         if self.verbatim:

   878             return text

   879         # compile the regexps once. do it here so one can see them.

   880         #

   881         # first the braces.

   882         if not self.__dict__.has_key('encode_re_braces'):

   883             self.encode_re_braces = re.compile(r'([{}])')

   884         text = self.encode_re_braces.sub(r'{\\\1}',text)

   885         if not self.__dict__.has_key('encode_re_bslash'):

   886             # find backslash: except in the form '{\{}' or '{\}}'.

   887             self.encode_re_bslash = re.compile(r'(?<!{)(\\)(?![{}]})')

   888         # then the backslash: except in the form from line above:

   889         # either '{\{}' or '{\}}'.

   890         text = self.encode_re_bslash.sub(r'{\\textbackslash}', text)

   891 

   892         # then dollar

   893         text = text.replace("$", '{\\$}')

   894         if not ( self.literal_block or self.literal or self.mathmode ):

   895             # the vertical bar: in mathmode |,\vert or \mid

   896             #   in textmode \textbar

   897             text = text.replace("|", '{\\textbar}')

   898             text = text.replace("<", '{\\textless}')

   899             text = text.replace(">", '{\\textgreater}')

   900         # then

   901         text = text.replace("&", '{\\&}')

   902         # the ^:

   903         # * verb|^| does not work in mbox.

   904         # * mathmode has wedge. hat{~} would also work.

   905         # text = text.replace("^", '{\\ensuremath{^\\wedge}}')

   906         text = text.replace("^", '{\\textasciicircum}')

   907         text = text.replace("%", '{\\%}')

   908         text = text.replace("#", '{\\#}')

   909         text = text.replace("~", '{\\textasciitilde}')

   910         # Separate compound characters, e.g. "--" to "-{}-".  (The

   911         # actual separation is done later; see below.)

   912         separate_chars = '-'

   913         if self.literal_block or self.literal:

   914             # In monospace-font, we also separate ",,", "``" and "''"

   915             # and some other characters which can't occur in

   916             # non-literal text.

   917             separate_chars += ',`\'"<>'

   918             # pdflatex does not produce doublequotes for ngerman.

   919             text = self.babel.double_quotes_in_tt(text)

   920             if self.font_encoding == 'OT1':

   921                 # We're using OT1 font-encoding and have to replace

   922                 # underscore by underlined blank, because this has

   923                 # correct width.

   924                 text = text.replace('_', '{\\underline{ }}')

   925                 # And the tt-backslash doesn't work in OT1, so we use

   926                 # a mirrored slash.

   927                 text = text.replace('\\textbackslash', '\\reflectbox{/}')

   928             else:

   929                 text = text.replace('_', '{\\_}')

   930         else:

   931             text = self.babel.quote_quotes(text)

   932             if not self.inside_citation_reference_label:

   933                 text = text.replace("_", '{\\_}')

   934         for char in separate_chars * 2:

   935             # Do it twice ("* 2") becaues otherwise we would replace

   936             # "---" by "-{}--".

   937             text = text.replace(char + char, char + '{}' + char)

   938         if self.insert_newline or self.literal_block:

   939             # Insert a blank before the newline, to avoid

   940             # ! LaTeX Error: There's no line here to end.

   941             text = text.replace("\n", '~\\\\\n')

   942         elif self.mbox_newline:

   943             if self.literal_block:

   944                 closings = "}" * len(self.literal_block_stack)

   945                 openings = "".join(self.literal_block_stack)

   946             else:

   947                 closings = ""

   948                 openings = ""

   949             text = text.replace("\n", "%s}\\\\\n\\mbox{%s" % (closings,openings))

   950         text = text.replace('[', '{[}').replace(']', '{]}')

   951         if self.insert_none_breaking_blanks:

   952             text = text.replace(' ', '~')

   953         if self.latex_encoding != 'utf8':

   954             text = self.unicode_to_latex(text)

   955             text = self.ensure_math(text)

   956         return text

   957 

   958     def attval(self, text,

   959                whitespace=re.compile('[\n\r\t\v\f]')):

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

   961         return self.encode(whitespace.sub(' ', text))

   962 

   963     def astext(self):

   964         if self.pdfinfo is not None and self.pdfauthor:

   965             self.pdfinfo.append('pdfauthor={%s}' % self.pdfauthor)

   966         if self.pdfinfo:

   967             pdfinfo = '\\hypersetup{\n' + ',\n'.join(self.pdfinfo) + '\n}\n'

   968         else:

   969             pdfinfo = ''

   970         head = '\\title{%s}\n\\author{%s}\n\\date{%s}\n' % \

   971                (self.title,

   972                 ' \\and\n'.join(['~\\\\\n'.join(author_lines)

   973                                  for author_lines in self.author_stack]),

   974                 self.date)

   975         return ''.join(self.head_prefix + [head] + self.head + [pdfinfo]

   976                         + self.body_prefix  + self.body + self.body_suffix)

   977 

   978     def visit_Text(self, node):

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

   980 

   981     def depart_Text(self, node):

   982         pass

   983 

   984     def visit_address(self, node):

   985         self.visit_docinfo_item(node, 'address')

   986 

   987     def depart_address(self, node):

   988         self.depart_docinfo_item(node)

   989 

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

   991         self.body.append('\\begin{center}\\begin{sffamily}\n')

   992         self.body.append('\\fbox{\\parbox{\\admonitionwidth}{\n')

   993         if name:

   994             self.body.append('\\textbf{\\large '+ self.language.labels[name] + '}\n');

   995         self.body.append('\\vspace{2mm}\n')

   996 

   997 

   998     def depart_admonition(self, node=None):

   999         self.body.append('}}\n') # end parbox fbox

  1000         self.body.append('\\end{sffamily}\n\\end{center}\n');

  1001 

  1002     def visit_attention(self, node):

  1003         self.visit_admonition(node, 'attention')

  1004 

  1005     def depart_attention(self, node):

  1006         self.depart_admonition()

  1007 

  1008     def visit_author(self, node):

  1009         self.visit_docinfo_item(node, 'author')

  1010 

  1011     def depart_author(self, node):

  1012         self.depart_docinfo_item(node)

  1013 

  1014     def visit_authors(self, node):

  1015         # not used: visit_author is called anyway for each author.

  1016         pass

  1017 

  1018     def depart_authors(self, node):

  1019         pass

  1020 

  1021     def visit_block_quote(self, node):

  1022         self.body.append( '\\begin{quote}\n')

  1023 

  1024     def depart_block_quote(self, node):

  1025         self.body.append( '\\end{quote}\n')

  1026 

  1027     def visit_bullet_list(self, node):

  1028         if 'contents' in self.topic_classes:

  1029             if self.use_latex_toc:

  1030                 raise nodes.SkipNode

  1031             self.body.append( '\\begin{list}{}{}\n' )

  1032         else:

  1033             self.body.append( '\\begin{itemize}\n' )

  1034 

  1035     def depart_bullet_list(self, node):

  1036         if 'contents' in self.topic_classes:

  1037             self.body.append( '\\end{list}\n' )

  1038         else:

  1039             self.body.append( '\\end{itemize}\n' )

  1040 

  1041     # Imperfect superscript/subscript handling: mathmode italicizes

  1042     # all letters by default.

  1043     def visit_superscript(self, node):

  1044         self.body.append('$^{')

  1045         self.mathmode = 1

  1046 

  1047     def depart_superscript(self, node):

  1048         self.body.append('}$')

  1049         self.mathmode = 0

  1050 

  1051     def visit_subscript(self, node):

  1052         self.body.append('$_{')

  1053         self.mathmode = 1

  1054 

  1055     def depart_subscript(self, node):

  1056         self.body.append('}$')

  1057         self.mathmode = 0

  1058 

  1059     def visit_caption(self, node):

  1060         self.body.append( '\\caption{' )

  1061 

  1062     def depart_caption(self, node):

  1063         self.body.append('}')

  1064 

  1065     def visit_caution(self, node):

  1066         self.visit_admonition(node, 'caution')

  1067 

  1068     def depart_caution(self, node):

  1069         self.depart_admonition()

  1070 

  1071     def visit_title_reference(self, node):

  1072         self.body.append( '\\titlereference{' )

  1073 

  1074     def depart_title_reference(self, node):

  1075         self.body.append( '}' )

  1076 

  1077     def visit_citation(self, node):

  1078         # TODO maybe use cite bibitems

  1079         if self._use_latex_citations:

  1080             self.context.append(len(self.body))

  1081         else:

  1082             self.body.append('\\begin{figure}[b]')

  1083             for id in node['ids']:

  1084                 self.body.append('\\hypertarget{%s}' % id)

  1085 

  1086     def depart_citation(self, node):

  1087         if self._use_latex_citations:

  1088             size = self.context.pop()

  1089             label = self.body[size]

  1090             text = ''.join(self.body[size+1:])

  1091             del self.body[size:]

  1092             self._bibitems.append([label, text])

  1093         else:

  1094             self.body.append('\\end{figure}\n')

  1095 

  1096     def visit_citation_reference(self, node):

  1097         if self._use_latex_citations:

  1098             self.body.append('\\cite{')

  1099             self.inside_citation_reference_label = 1

  1100         else:

  1101             href = ''

  1102             if node.has_key('refid'):

  1103                 href = node['refid']

  1104             elif node.has_key('refname'):

  1105                 href = self.document.nameids[node['refname']]

  1106             self.body.append('[\\hyperlink{%s}{' % href)

  1107 

  1108     def depart_citation_reference(self, node):

  1109         if self._use_latex_citations:

  1110             self.body.append('}')

  1111             self.inside_citation_reference_label = 0

  1112         else:

  1113             self.body.append('}]')

  1114 

  1115     def visit_classifier(self, node):

  1116         self.body.append( '(\\textbf{' )

  1117 

  1118     def depart_classifier(self, node):

  1119         self.body.append( '})\n' )

  1120 

  1121     def visit_colspec(self, node):

  1122         self.active_table.visit_colspec(node)

  1123 

  1124     def depart_colspec(self, node):

  1125         pass

  1126 

  1127     def visit_comment(self, node):

  1128         # Escape end of line by a new comment start in comment text.

  1129         self.body.append('%% %s \n' % node.astext().replace('\n', '\n% '))

  1130         raise nodes.SkipNode

  1131 

  1132     def visit_compound(self, node):

  1133         pass

  1134 

  1135     def depart_compound(self, node):