Documentation update

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

1 files changed, 87 insertions, 9 deletions

diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index fddc00864..de58bca9a 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -1059,8 +1059,9 @@ __ rst/alternatives.html#or-not-to-do
   applicable to any output format.  Using a standard, such as MathML_,
   would be best.  TeX (or itex_) would be acceptable as a *front-end*
   to MathML. A simpler, alternative input format is defined by
-  ASCIIMathML_ and Microsoft's `Linear Format Math`_.
-  See `the culmination of a relevant discussion
+  ASCIIMathML_ and Microsoft's
+  `Unicode Nearly Plain Text Encoding of Mathematics`_. See `the
+  culmination of a relevant discussion
   <http://article.gmane.org/gmane.text.docutils.user/118>`__.
 
   Build on existing extensions (`latex_math`_, `math support in Sphinx`_).
@@ -1082,8 +1083,8 @@ __ rst/alternatives.html#or-not-to-do
   .. _MathML: http://www.w3.org/TR/MathML2/
   .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
   .. _ASCIIMathML: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
-  .. _Linear Format Math:
-     http://www.unicode.org/notes/tn28/UTN28-PlainTextMath-v2.pdf
+  .. _Unicode Nearly Plain Text Encoding of Mathematics:
+     http://www.unicode.org/notes/tn28/UTN28-PlainTextMath-v3.pdf
 
 
 
@@ -1689,6 +1690,69 @@ nodes. This makes the document model and the writers somewhat simpler.
 
   Keep the special admonition directives in reStructuredText syntax?
 
+* _`Line numbers` and "source" in system messages:
+
+  - Add "source" and "line" keyword arguments to all Reporter calls?
+    This would require passing source/line arguments along all
+    intermediate functions (where currently only `line` is used).
+
+    Or rather specify "line" only if actually needed?
+
+    Currently, `document.reporter` uses a state machine instance to
+    determine the "source" and "line" info from
+    `statemachine.input_lines` if not given explicitely. Except for
+    special cases, the "line" argument is not needed because,
+    `document.statemachine` keeps record of the current line number.
+
+  - For system messages generated after the parsing is completed (i.e. by
+    transforms or the writer) "line" info must be present in the doctree
+    elements.
+
+    Elements' .line assignments should be checked.  (Assign to .source
+    too?  Add a set_info method?  To what?)
+
+    The "source" (and line number in the source) can either be added
+    explicitely to the elements or determined from the “raw” line
+    number by `document.statemachine.get_source_and_line`.
+
+  - Some line numbers in elements are not being set properly
+    (explicitly), just implicitly/automatically.  See rev. 1.74 of
+    docutils/parsers/rst/states.py for an example of how to set.
+
+  - The line numbers of definition list items are wrong::
+
+        $ rst2pseudoxml.py --expose-internal-attribute line
+        1
+          2
+          3
+
+        5
+          6
+          7
+
+        <document source="<stdin>">
+            <definition_list>
+                <definition_list_item internal:line="3">
+                    <term>
+                        1
+                    <definition>
+                        <paragraph internal:line="2">
+                            2
+                            3
+                <definition_list_item internal:line="6">
+                    <term>
+                        5
+                    <definition>
+                        <paragraph internal:line="6">
+                            6
+                            7
+
+* .. _none source:
+
+  Quite a few nodes are getting a "None" source attribute as well.  In
+  particular, see the bodies of definition lists.
+
+
 
 Unimplemented Transforms
 ========================
@@ -1717,13 +1781,13 @@ Unimplemented Transforms
 
        + based on bibstuff_?
        + also have a look at
-        
+
 	 * CrossTeX_, a backwards-compatible, improved bibtex
 	   re-implementation in Python (including HTML export).
 	   (development stalled since 2 years)
-	   
+
          * Pybtex_,a drop-in replacement for BibTeX written in Python.
-	 
+
 	   * BibTeX styles & (experimental) pythonic style API.
 	   * Database in BibTeX, BibTeXML and YAML formats.
 	   * full Unicode support.
@@ -2149,9 +2213,9 @@ Which packages do we want to use?
 * enumeration environment, field list
 
   * use `mdwlist` from texlive-latex-recommended?
-  
+
   * use `eqlist` (texlive-latex-extra) for field-lists?
-  
+
 
 * ``--use-latex-when-possible`` »super option« that would set the
   following::
@@ -2298,6 +2362,20 @@ Missing features
   Put in place of the to-be-implemented "citations" directive
   (see `Footnote & Citation Gathering`_).
 
+* The latex writer ignores any inline markup in document titles and
+  subtitles (but it respects it in section titles)::
+
+      This is the *Title*
+      ===================
+
+      This is the *Subtitle*
+      ----------------------
+
+      This is a *section title*
+      ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+      This is the document.
+
 
 Unicode to LaTeX
 ````````````````