From a8cc047c898f5f0e064250e810a2d47c053299b5 Mon Sep 17 00:00:00 2001 From: milde Date: Wed, 28 Apr 2010 12:30:22 +0000 Subject: [PATCH] Documentation update git-svn-id: https://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils@6316 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- BUGS.txt | 74 ------------------------------------------ docs/dev/todo.txt | 96 +++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 87 insertions(+), 83 deletions(-) diff --git a/BUGS.txt b/BUGS.txt index 4dc86077d..ec0d21af3 100644 --- a/BUGS.txt +++ b/BUGS.txt @@ -130,15 +130,6 @@ Known Bugs Also see the `SourceForge Bug Tracker`_. -* The HTML writer generates invalid XHTML for _`centered images with - targets`:: - - .. image:: example.png - :align: center - :target: http://docutils.sourceforge.net/ - - This results in ``
``, which is invalid. - * .. _error reporting: Calling rst2s5.py with a non-existent theme (``--theme @@ -162,71 +153,6 @@ Also see the `SourceForge Bug Tracker`_. For details, see `this posting by Alan G. Isaac `_. -* _`Line numbers` and "source" in system messages are inconsistent. - - - In text inserted by the "include" directive, errors are often not - reported with the correct "source" or "line" numbers. - - This is partially fixed in the commits from 2009-09-25 and 2009-10-28. - The test in test/test_parsers/test_rst/test_directives/test_include.py - works, but there are still plenty of system messages pointing to the - wrong spot. - - - Perhaps all Reporter calls need "source" and "line" keyword arguments? - - Alternatively, give `document.reporter` access to the state machine - instance `document.statemachine` and extract the "source" and "line" - info from `statemachine.input_lines`. - Except for special cases, there is even no need to call with "line": - During parsing, `document.statemachine` knows 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) could either be added - explicitely to the elements or determined from the “raw” line number by - `document.statemachine.get_source_spot`. - - - 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 - - - - - - 1 - - - 2 - 3 - - - 5 - - - 6 - 7 - -* .. _none source: - - Quite a few nodes are getting a "None" source attribute as well. In - particular, see the bodies of definition lists. - * Footnote label "5" should be "4" when processing the following input:: diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fddc00864..de58bca9a 100644 --- a/docs/dev/todo.txt +++ b/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 `__. 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 + + + + + + 1 + + + 2 + 3 + + + 5 + + + 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 ```````````````` -- 2.11.4.GIT