Hyperlinked footnote marks and support for symbol footnotes

with ``--use-latex-footnotes``.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@6127 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

6 files changed, 79 insertions, 23 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index b0e28c8a7..b46066d83 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -137,7 +137,9 @@ Changes Since 0.5
   - Typeset generic topic as "quote block with title".
   - Use template (file and configuration option).
   - Render doctest blocks as literal blocks (fixes [ 1586058 ]).
-  - Use .translate() instead of repeated .replace() calls.
+  - Use `translate` instead of repeated `replace` calls for text encoding.
+  - Hyperlinked footnote marks and support for symbol footnotes with
+    ``--use-latex-footnotes``.
 
 * docutils/writers/manpage.py
 
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index a09aebb90..b23577384 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -544,6 +544,9 @@ General
       -- `Easy Slide Shows With reStructuredText & S5
       <../user/slide-shows.html>`_
 
+  Analogue to the ``sectnum_xform`` setting, it could be used by the
+  latex writer to switch to a LaTeX generated ToC (currently, the latex
+  writer calls it "use_latex_toc").
 
 Documentation
 =============
@@ -1912,11 +1915,6 @@ Bug fixes
 * Too deeply nested lists fail: generate a warning and provide
   a workaround.
 
-* Symbol footnotes fail with "use_latex_footnotes".
-
-  For a possible fix see
-  http://help-csli.stanford.edu/tex/latex-footnotes.shtml
-
 
 Generate clean and configurable LaTeX source
 ----------------------------------------------
@@ -1965,11 +1963,12 @@ Which packages do we want to use?
 
 * footnotes
 
-  + enable symbolic footnotes (parallel to numeric)
-
   + document customization (links to how-to and packages)
+  
+  + True footnotes with LaTeX auto-numbering? (as option?)
 
-  + find out how to link and back-link to footnotes with `hyperref`
+  + Add back-links (analogue to the system message, but in the
+    \DUfootnotetext and \DUfootnotemark cmds).
 
     The `hyperref` manual says:
 
diff --git a/docutils/docs/user/docutils-05-compat.sty.txt b/docutils/docs/user/docutils-05-compat.sty.txt
index 898adc76e..ce0857841 100644
--- a/docutils/docs/user/docutils-05-compat.sty.txt
+++ b/docutils/docs/user/docutils-05-compat.sty.txt
@@ -88,6 +88,7 @@ __ ../ref/rst/directives.html#document-header-footer
       ``--literal-block-env=lstlistings`` fail with literal or doctest
       blocks nested in an admonition.
 
+* Support symbol footnotes with ``--use-latex-footnotes``.
 
 Backwards compatibility:
   "Bug for bug compatibility" is not provided.
@@ -642,6 +643,12 @@ New Feature:
   :topic:      ``\DUtopic`` and ``\DUtitle`` commands,
   :transition: ``\DUtransition`` command.
 
+  Auxiliary LaTeX commands
+
+  :footnotes: ``\DUfootnotemark`` and ``\DUfootnotetext`` commands with
+	      hyperlink support and choice of footnotemark format (symbol or
+	      numeric).
+
 Backwards compatibility:
   In most cases, the default definition corresponds to the previously used
   construct. The following definitions restore the old behaviour in case of
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index ad56c2052..aa1ad4c54 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -1429,8 +1429,6 @@ Workaround:
   ``use-latex-citations`` options.
 
   * Use LaTeX footnotes and citations for printing or more complex layout.
-  * Footnotes and citations done with figures might excell in hyperlink
-    support.
 
 If ``use-latex-citations`` is used, a bibliography is inserted right at
 the end of the document. *This should be customizable*.
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index a24b1f3f2..3d7237d8a 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -402,6 +402,18 @@ PreambleCmds.fieldlist = r"""
 PreambleCmds.float_settings = r"""\usepackage{float} % float configuration
 \floatplacement{figure}{H} % place figures here definitely"""
 
+PreambleCmds.footnotes = r"""% numeric or symbol footnotes with hyperlinks
+\providecommand*{\DUfootnotemark}[3]{{%
+  \renewcommand{\thefootnote}{\csname #2\endcsname{footnote}}%
+  \hyperlink{#1}{\footnotemark[#3]}%
+}}
+\providecommand{\DUfootnotetext}[4]{{%
+  \renewcommand{\thefootnote}{%
+    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+    \csname #2\endcsname{footnote}}%
+  \footnotetext[#3]{#4}%
+}}"""
+
 PreambleCmds.footnote_floats = r"""% settings for footnotes as floats:
 \setlength{\floatsep}{0.5em}
 \setlength{\textfloatsep}{\fill}
@@ -816,6 +828,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
     has_latex_toc = False # is there a toc in the doc? (needed by minitoc)
     is_toc_list = False   # is the current bullet_list a ToC?
     section_level = 0
+    footnotesymbols = ['*'] # footnote symbols in order of appearance
 
     # Flags to encode():
     # inside citation reference labels underscores dont need to be escaped
@@ -1209,6 +1222,20 @@ class LaTeXTranslator(nodes.NodeVisitor):
     ##     body = ''.join(self.body_prefix  + self.body + self.body_suffix)
     ##     return head + '\n' + body
 
+    def footnotesymbol_number(self, symbol):
+        """Return running number for a footnote symbol"""
+        try:
+            i = self.footnotesymbols.index(symbol) + 1
+        except ValueError:
+            self.footnotesymbols.append(symbol)
+            i = len(self.footnotesymbols)
+            if i % 9 == 0:
+                warn = self.document.reporter.warning
+                warn('symbol footnote ``[*]_``\n'
+                     'LaTeX supports only 9 different footnote symbols. '
+                     'Starting again with "*".')
+        return (i+1) % 9 or 9
+
     def is_inline(self, node):
         """Check whether a node represents an inline element"""
         return isinstance(node.parent, nodes.TextElement)
@@ -1824,14 +1851,21 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def visit_footnote(self, node):
         if self.use_latex_footnotes:
+            self.fallbacks['footnotes'] = PreambleCmds.footnotes
             num,text = node.astext().split(None,1)
-            num = self.encode(num.strip())
-            self.out.append('\\footnotetext['+num+']')
-            self.out.append('{')
+            try:
+                i = int(num)
+                format = 'arabic'
+            except ValueError:
+                i = self.footnotesymbol_number(num)
+                format = 'fnsymbol'
+            self.out.append('%%\n\\DUfootnotetext{%s}{%s}{%d}{' %
+                            (node['ids'][0], format, i))
+            if node['ids'] == node['names']:
+                self.out += self.ids_to_labels(node)
         else:
             # use key starting with ~ for sorting after small letters
-            self.requirements['~footnote_floats'] = (
-                                            PreambleCmds.footnote_floats)
+            self.requirements['~fnt_floats'] = PreambleCmds.footnote_floats
             self.out.append('\\begin{figure}[b]')
             self.append_hypertargets(node)
             if node.get('id') == node.get('name'):  # explicite label
@@ -1844,7 +1878,13 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.out.append('\\end{figure}\n')
 
     def visit_footnote_reference(self, node):
+        href = ''
+        if 'refid' in node:
+            href = node['refid']
+        elif 'refname' in node:
+            href = self.document.nameids[node['refname']]
         if self.use_latex_footnotes:
+            self.fallbacks['footnotes'] = PreambleCmds.footnotes
             # TODO: insert footnote content at (or near) this place
             # print "footnote-ref to", node['refid']
             # footnotes = (self.document.footnotes +
@@ -1854,13 +1894,16 @@ class LaTeXTranslator(nodes.NodeVisitor):
             #     # print footnote['ids']
             #     if node.get('refid', '') in footnote['ids']:
             #         print 'matches', footnote['ids']
-            self.out.append('\\footnotemark['+self.encode(node.astext())+']')
+            num = node.astext()
+            try:
+                i = int(num)
+                format = 'arabic'
+            except ValueError:
+                i = self.footnotesymbol_number(num)
+                format = 'fnsymbol'
+            self.out.append(r'\DUfootnotemark{%s}{%s}{%d}' %
+                            (href, format, i))
             raise nodes.SkipNode
-        href = ''
-        if 'refid' in node:
-            href = node['refid']
-        elif 'refname' in node:
-            href = self.document.nameids[node['refname']]
         format = self.settings.footnote_references
         if format == 'brackets':
             suffix = '['
diff --git a/docutils/docutils/writers/latex2e/docutils-05-compat.sty b/docutils/docutils/writers/latex2e/docutils-05-compat.sty
index c54b9b7ef..aff41d2db 100644
--- a/docutils/docutils/writers/latex2e/docutils-05-compat.sty
+++ b/docutils/docutils/writers/latex2e/docutils-05-compat.sty
@@ -7,7 +7,7 @@
 % 
 % :Author:    Guenter Milde
 % :Contact:   milde@users.berlios.de
-% :Revision:  $Revision: 6111 $
+% :Revision:  $Revision: 6115 $
 % :Date:      $Date: 2009-02-24$
 % :Copyright: © 2009 G. Milde,
 %             Released  without warranties or conditions of any kind
@@ -88,6 +88,7 @@
 %       ``--literal-block-env=lstlistings`` fail with literal or doctest
 %       blocks nested in an admonition.
 % 
+% * Support symbol footnotes with ``--use-latex-footnotes``.
 % 
 % Backwards compatibility:
 %   "Bug for bug compatibility" is not provided.
@@ -642,6 +643,12 @@
 %   :topic:      ``\DUtopic`` and ``\DUtitle`` commands,
 %   :transition: ``\DUtransition`` command.
 % 
+%   Auxiliary LaTeX commands
+% 
+%   :footnotes: ``\DUfootnotemark`` and ``\DUfootnotetext`` commands with
+%               hyperlink support and choice of footnotemark format (symbol or
+%               numeric).
+% 
 % Backwards compatibility:
 %   In most cases, the default definition corresponds to the previously used
 %   construct. The following definitions restore the old behaviour in case of