Update TODO documentation.

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

2 files changed, 77 insertions, 131 deletions

diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 76e8839a7..6455318cd 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -2447,29 +2447,39 @@ Bug fixes
 
 * Paragraph following field-list or table in compound is indented.
 
-  This is a problem with the current DUfieldlist definition and with
-  the use of "longtable" for tables.
-  See `LaTeX constructs and packages instead of re-implementations`_ for
-  alternatives.
+  This is a problem with the current DUfieldlist definition and with the
+  use of "longtable" for tables. See `other LaTeX constructs and packages
+  instead of re-implementations`_ for alternatives.
 
 
 Generate clean and configurable LaTeX source
 ----------------------------------------------
 
-* Check the generated source with package `nag`.
+Which packages do we want to use?
+
++ base and "recommended" packages
+
+  (packages that should be in a "reasonably sized and reasonably modern
+  LaTeX installation like the `texlive-latex-recommended` Debian package,
+  say):
+
++ No "fancy" or "exotic" requirements.
+
++ pointers to advanced packages and their use in the `latex writer
+  documentation`_.
 
 Configurable placement of figure and table floats
 `````````````````````````````````````````````````
 
 * Special class argument to individually place figures?
 
-  Either:
-
-    placement-<optional arg>  -> \figure[<optional arg>]{...}
+  Example::
 
-  e.g. ``.. class::  placement-htb``,
+    .. figure:: foo.pdf
+       :class: place-here-if-possible place-top place-bottom
 
-  or more verbose:
+  would be written as ``\figure[htb]{...}`` with
+  the optional args:
 
   :H: place-here
   :h: place-here-if-possible
@@ -2477,120 +2487,78 @@ Configurable placement of figure and table floats
   :b: place-bottom
   :p: place-on-extra-page
 
-  e.g.: ``.. class:: place-here-if-possible place-top place-bottom``
-
-  Maybe support both variants?
-
-
-LaTeX constructs and packages instead of re-implementations
-```````````````````````````````````````````````````````````
-
-Which packages do we want to use?
-
-  + base and "recommended" packages
-
-    (packages that should be in a "reasonably sized and reasonably modern
-    LaTeX installation like the `texlive-latex-recommended` Debian package,
-    say):
+  Alternative: class value = "place-" + optional arg, e.g. ``:class:
+  place-htb``.
 
-  + No "fancy" or "exotic" requirements.
-
-  + pointers to advanced packages and their use in the `latex writer
-    documentation`_.
-
-* footnotes
-
-  + True footnotes with LaTeX auto-numbering (as option ``--latex-footnotes``)
-    (also for target-footnotes):
-
-    - attach footnote text to footnote-symobol node
-    - write \footnote{<footnote text>}
-    - consider cases where LaTeX does not support footnotes
-      (inside tables, headings, ...)?
-    - consider multiple footnote refs to common footnote text.
-
-    .. Quote:
-
-     If the symbol you want is not one of the ones listed, you'll need to
-     redefine ``\@fnsymbol`` and add it, e.g. perhaps like::
-
-      \def\@fnsymbol#1{\ifcase#1\hbox{}\or *\or \dagger\or \ddagger\or
-      \mathchar "278\or \mathchar "27B\or \|\or **\or \dagger\dagger \or
-      \ddagger\ddagger \or \mathchar"27C \else\@ctrerr\fi\relax}
-
-     which would allow \symbolfootnote[10]{footnote} to have a club as its
-     mark.
-
-  + document customization (links to how-to and packages):
+Footnotes
+`````````
 
-  .. Footnote packages:
++ True footnotes with LaTeX auto-numbering (as option ``--latex-footnotes``)
+  (also for target-footnotes):
+  Write ``\footnote{<footnote content>}`` at the place of the
+  ``<footnote_reference>`` node.
 
-     :footnote: texlive-latex-recommended % savenotes environment
-     :footmisc: texlive-latex-extra       % formatting options
-     :manyfoot: texlive-latex-extra
-     :bigfoot: texlive-latex-extra
-     :perpage: texlive-latex-extra
-     :ftnxtra: new on CTAN
-               fixes the issue of footnote inside \caption{},
-               tabular environment and \section{} like commands.
++ Open questions:
 
+  - Load hyperref_ with option "hyperfootnotes" and/or
+    package footnotebackref_ or leave this to the user?
 
-     German tutorial:
-     http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf
+  - Consider cases where LaTeX does not support footnotes
+    (inside tables__, headings__, caption, ...).
+    Use ftnxtra_, tabularx_, tabulary_, longtable_?
 
-  .. Footnote FAQs:
+    __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab
+    __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect
 
-     `Footnotes whose texts are identical
-     <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=repfootnote>`__
+  - Consider `multiple footnote refs to common footnote text`__.
 
-     * label per hand or use footmisc
+    KOMA-script classes and the KOMA scrextend_ package provide
+    ``\footref`` that can be used for additional references to a
+    ``\label``-ed footnote. Since 2021-05-01, ``\footref`` is provided
+    by the LaTeX core, too.
 
-     `More than one sequence of footnotes
-     <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot>`__
+    __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot
 
-     * manyfoot, bigfoot
+  - Consider numbered vs. symbolic footnotes.
 
-     `Footnotes in tables
-     <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab>`__
++ document customization (links to how-to and packages)
 
-     * `tabularx` and longtable allow footnotes.
-     * `footnote` provides a "savenotes" environment which collects all
-       footnotes and emits them at ``end{savenotes}``
+.. Footnote packages at CTAN (www.ctan.org/pkg/<packagename>):
 
-     `Footnotes in LaTeX section headings
-     <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect>`__
+   :footnote: provides a "savenotes" environment which collects all
+              footnotes and emits them at ``end{savenotes}``
+              (texlive-latex-recommended)
 
-     * Take advantage of the fact that the mandatory argument doesn't
-       move if the optional argument is present::
+   :ftnxtra_: fixes the issue of footnote inside \caption{},
+             tabular environment and \section{} like commands.
 
-           \section[title] {title\footnote{title ftnt}}
+   :footnotebackref_: bidirectional links to/from footnote mark to
+                      footnote text.
 
-     * Use the footmisc package, with package option stable - this modifies
-       footnotes so that they softly and silently vanish away if used in a
-       moving argument.
+.. Footnote Discussion:
 
-     * Use ftnxtra.
+   `German tutorial
+   <http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf>`__
 
-     `Footnotes numbered per page
-     <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footnpp>`__
+   `wikibooks: footnote workarounds
+   <https://en.wikibooks.org/wiki/LaTeX/Footnotes_and_Margin_Notes#Common_problems_and_workarounds>`__
 
-     * perpage provides a general mechanism for resetting counters per page
-     * footmisc provides a package option perpage
+.. _footnotebackref: https://www.ctan.org/pkg/footnotebackref
+.. _ftnxtra: https://www.ctan.org/pkg/ftnxtra
+.. _hyperref: https://www.ctan.org/pkg/hyperref
+.. _longtable: https://www.ctan.org/pkg/longtable
+.. _scrextend: https://www.ctan.org/pkg/longtable
+.. _tabularx: https://www.ctan.org/pkg/tabularx
 
-* use `eqlist` or `enumitem` (texlive-latex-extra) for field-lists?
 
-* ``--use-latex-when-possible`` »super option« that would set the
-  following::
+Other LaTeX constructs and packages instead of re-implementations
+`````````````````````````````````````````````````````````````````
 
-      --no-section-numbering
-      --use-latex-toc
-      --use-latex-docinfo
-      --use-latex-abstract
-      --use-latex-footnotes
-      --use-latex-citations
+* Check the generated source with package `nag`.
 
-   ? (My preference is to default to use-latex-* whenever possible [GM])
+* enumitem_ (texlive-latex-extra) for field-lists?
 
+.. _enumitem: https://www.ctan.org/pkg/enumitem
 
 Default layout
 --------------
@@ -2624,12 +2592,8 @@ Default layout
      -  \\ % subtitle%
      +  \\[0.5em] % subtitle%
 
-.. _PSNFSS documentation:
-   http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf
 .. _compound paragraph:
    ../ref/rst/directives.html#compound-paragraph
-.. _fixltx2e:
-   http://mirror.ctan.org/help/Catalogue/entries/fixltx2e.html
 
 Tables
 ``````
@@ -2642,8 +2606,7 @@ Tables
   + use tabularx column type ``X`` and let LaTeX decide width, or
   + use tabulary_?
 
-  .. _tabulary:
-     http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=tabulary
+  .. _tabulary: https://www.ctan.org/pkg/tabulary
 
 * From comp.text.tex (13. 4. 2011):
 
@@ -2751,22 +2714,6 @@ that lists LaTeX counterparts for a wide range of Unicode characters.
 
 .. _bibstuff: http://code.google.com/p/bibstuff/
 
-Allow choice between utf8 (standard) and utf8x (extended) encodings
-```````````````````````````````````````````````````````````````````
-
-* Allow the user to select *utf8* or *utf8x* LaTeX encoding. (Docutil's
-  output encoding becomes LaTeX's input encoding.)
-
-The `ucs` package provides extended support for UTF-8 encoding in LaTeX
-via the `inputenc`-option ``utf8x``.  It is, however, a non-standard
-extension and no longer developed.
-
-Ideas:
-  a) Python has 4 names for the UTF-8 encoding (``utf_8, U8, UTF, utf8``)
-     give a special meaning to one of the aliases,
-
-  b) scan "stylesheets" and "latex-preamble" options and use ``utf8x``
-     if it contains ``ucs``
 
 XeTeX writer
 ````````````
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index f72e4cab0..d01177b2b 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -2257,15 +2257,14 @@ class LaTeXTranslator(nodes.NodeVisitor):
         elif 'refname' in node:
             href = self.document.nameids[node['refname']]
         # if not self.docutils_footnotes:
-            # TODO: insert footnote content at (or near) this place
-            # print("footnote-ref to", node['refid'])
-            # footnotes = (self.document.footnotes +
-            #              self.document.autofootnotes +
-            #              self.document.symbol_footnotes)
-            # for footnote in footnotes:
-            #     # print(footnote['ids'])
-            #     if node.get('refid', '') in footnote['ids']:
-            #         print('matches', footnote['ids'])
+        #     # TODO: insert footnote content at (or near) this place
+        #     #       see also docs/dev/todo.txt
+        #     try:
+        #         referenced_node = self.document.ids[node['refid']]
+        #     except (AttributeError, KeyError):
+        #         self.document.reporter.error(
+        #             'unresolved footnote-reference %s' % node)
+        #     print('footnote-ref to %s' % referenced_node)
         format = self.settings.footnote_references
         if format == 'brackets':
             self.append_hypertargets(node)