Permalink
Browse files

directly check in docutils and jinja2

  • Loading branch information...
1 parent 2cb8615 commit 25e2d10774151b755cd2f7cdc616ee6da0dd6b33 @jschementi committed Feb 26, 2010
Showing 774 changed files with 179,425 additions and 0 deletions.
View
@@ -0,0 +1,361 @@
+================
+ Docutils_ Bugs
+================
+
+:Author: David Goodger; open to all Docutils developers
+:Contact: goodger@python.org
+:Date: $Date: 2009-11-11 13:00:17 +0100 (Mit, 11 Nov 2009) $
+:Revision: $Revision: 6193 $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that
+tend to stay in the shadows and don't bother anybody. Once in a while
+new bugs are born. From time to time some bugs (new and old) crawl
+out into the light and must be dealt with. Icky.
+
+This document describes how to report a bug, and lists known bugs.
+
+.. contents::
+
+
+How To Report A Bug
+===================
+
+If you think you've discovered a bug, please read through these
+guidelines before reporting it.
+
+First, make sure it's a new bug:
+
+* Please check the list of `known bugs`_ below and the `SourceForge
+ Bug Tracker`_ to see if it has already been reported.
+
+* Are you using the very latest version of Docutils? The bug may have
+ already been fixed. Please get the latest version of Docutils from
+ the repository_ or from the current snapshot_ and check again. Even
+ if your bug has not been fixed, others probably have, and you're
+ better off with the most up-to-date code.
+
+ If you don't have time to check the latest snapshot, please report
+ the bug anyway. We'd rather tell you that it's already fixed than
+ miss reports of unfixed bugs.
+
+* If Docutils does not behave the way you expect, look in the
+ documentation_ (don't forget the FAQ_!) and `mailing list archives`_
+ for evidence that it should behave the way you expect.
+
+If you're not sure, please ask on the Docutils-users_ mailing list
+first.
+
+---------------------------------------------------------------------
+
+If it's a new bug, the most important thing you can do is to write a
+simple description and a recipe that reproduces the bug. Try to
+create a `minimal example`_ that demonstrates the bug. The easier you
+make it to understand and track down the bug, the more likely a fix
+will be.
+
+.. sidebar:: minimal example
+
+ .. _minimal example:
+
+ A minimal example is an example which is as small as possible. These
+ examples are much easier to understand than long examples.
+
+ To construct an example which is as small as possible, the rule is
+ quite simple: *remove anything which is not necessary*.
+
+ See also: `LaTeX FAQ`__, `Lilypond Documentation`__, minimalbeispiel.de__
+
+ __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
+ __ http://lilypond.org/doc/v2.9/Documentation/user/lilypond/Minimal-examples
+ __ http://www.minimalbeispiel.de/mini-en.html
+
+Now you're ready to write the bug report. Please include:
+
+* A clear description of the bug. Describe how you expected Docutils
+ to behave, and contrast that with how it actually behaved. While
+ the bug may seem obvious to you, it may not be so obvious to someone
+ else, so it's best to avoid a guessing game.
+
+* A complete description of the environment in which you reproduced
+ the bug:
+
+ - Your operating system & version.
+ - The version of Python (``python -V``).
+ - The version of Docutils (use the "-V" option to most Docutils
+ front-end tools).
+ - Any private modifications you made to Docutils.
+ - Anything else that could possibly be relevant. Err on the side
+ of too much information, rather than too little.
+
+* A literal transcript of the *exact* command you ran, and the *exact*
+ output. Use the "--traceback" option to get a complete picture.
+
+* The exact input and output files. Create a `minimal example`_
+ of the failing behaviour — it is better to attach complete files
+ to your bug report than to include just a summary or excerpt.
+
+* If you also want to include speculation as to the cause, and even a
+ patch to fix the bug, that would be great!
+
+The best place to send your bug report is to the `SourceForge Bug
+Tracker`_. That way, it won't be misplaced or forgotten. In fact, an
+open bug report on SourceForge is a constant irritant that begs to be
+squashed.
+
+Thank you!
+
+(This section was inspired by the `Subversion project's`__ BUGS__
+file.)
+
+__ http://subversion.tigris.org/
+__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
+
+.. _CVS: http://sourceforge.net/cvs/?group_id=38414
+.. _repository: docs/dev/repository.html
+.. _snapshot: http://docutils.sourceforge.net/#download
+.. _documentation: docs/
+.. _FAQ: FAQ.html
+.. _mailing list archives: http://docutils.sf.net/#mailing-lists
+.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
+.. _SourceForge Bug Tracker:
+ http://sourceforge.net/tracker/?group_id=38414&atid=422030
+
+
+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 ``<a><div><img /></div></a>``, which is invalid.
+
+* .. _error reporting:
+
+ Calling rst2s5.py with a non-existent theme (``--theme
+ does_not_exist``) or a non-existent language (``--language zz``)
+ causes exceptions. Such errors should be handled more gracefully.
+
+* The "stylesheet" setting (a URL, to be used verbatim) should be
+ allowed to be combined with "embed_stylesheet". The stylesheet data
+ should be read in using urllib. There was an assumption that a
+ stylesheet to be embedded should exist as a file on the local
+ system, and only the "stylesheet_path" setting should be used.
+
+* ``utils.relative_path()`` sometimes returns absolute _`paths on
+ Windows` (like ``C:/test/foo.css``) where it could have chosen a
+ relative path.
+
+ Furthermore, absolute pathnames are inserted verbatim, like
+ ``href="C:/test/foo.css"`` instead of
+ ``href="file:///C:/test/foo.css"``.
+
+ For details, see `this posting by Alan G. Isaac
+ <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
+
+* _`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
+
+ <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.
+
+* Footnote label "5" should be "4" when processing the following
+ input::
+
+ ref [#abc]_ [#]_ [1]_ [#4]_
+
+ .. [#abc] footnote
+ .. [#] two
+ .. [1] one
+ .. [#4] four
+
+ Output::
+
+ <document source="<stdin>">
+ <paragraph>
+ ref
+ <footnote_reference auto="1" ids="id1" refid="abc">
+ 2
+
+ <footnote_reference auto="1" ids="id2" refid="id5">
+ 3
+
+ <footnote_reference ids="id3" refid="id6">
+ 1
+
+ <footnote_reference auto="1" ids="id4" refid="id7">
+ 5
+ <footnote auto="1" backrefs="id1" ids="abc" names="abc">
+ <label>
+ 2
+ <paragraph>
+ footnote
+ <footnote auto="1" backrefs="id2" ids="id5" names="3">
+ <label>
+ 3
+ <paragraph>
+ two
+ <footnote backrefs="id3" ids="id6" names="1">
+ <label>
+ 1
+ <paragraph>
+ one
+ <footnote auto="1" backrefs="id4" ids="id7" names="4">
+ <label>
+ 5
+ <paragraph>
+ four
+
+* IDs are based on names. Explicit hyperlink targets have priority
+ over implicit targets. But if an explicit target comes after an
+ implicit target with the same name, the ID of the first (implicit)
+ target remains based on the implicit name. Since HTML fragment
+ identifiers based on the IDs, the first target keeps the name. For
+ example::
+
+ .. contents::
+
+ Section
+ =======
+
+ .. _contents:
+
+ Subsection
+ ----------
+
+ text with a reference to contents_ and section_
+
+ .. _section:
+
+ This paragraph is explicitly targeted with the name "section".
+
+ When processed to HTML, the 2 internal hyperlinks (to "contents" &
+ "section") will work fine, but hyperlinks from outside the document
+ using ``href="...#contents"`` and ``href="...#section"`` won't work.
+ Such external links will connect to the implicit targets (table of
+ contents and "Section" title) instead of the explicit targets
+ ("Subsection" title and last paragraph).
+
+ Hyperlink targets with duplicate names should be assigned new IDs
+ unrelated to the target names (i.e., "id"-prefix serial IDs).
+
+* The "contents" ID of the local table of contents in
+ ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
+ the HTML output at
+ ``test/functional/expected/standalone_rst_html4css1.html``.
+
+* _`Blank first columns` in simple tables with explicit row separators
+ silently swallow their input. They should at least produce system
+ error messages. But, with explicit row separators, the meaning is
+ unambiguous and ought to be supported::
+
+ ============== ==========
+ Table with row separators
+ ============== ==========
+ and blank
+ -------------- ----------
+ entries
+ -------------- ----------
+ in first
+ -------------- ----------
+ columns.
+ ============== ==========
+
+ Added a commented-out test case to
+ test/test_parsers/test_rst/test_SimpleTableParser.py.
+
+* _`Footnote references with hyperlink targets` cause a possibly
+ invalid node tree and make the HTML writer crash::
+
+ $ rst2pseudoxml.py
+ [1]_
+
+ .. _1: URI
+ <document source="<stdin>">
+ <paragraph>
+ <footnote_reference ids="id1" refuri="URI">
+ 1
+ <target ids="id2" names="1" refuri="URI">
+
+* Anonymous references have "name" attributes. Should they? Are they
+ used? See ``test/test_parsers/test_rst/test_inline_markup.py``.
+
+* <reference> elements have a "name" attribute, not "names". The
+ attribute should be "names"; this is an inconsistency.
+
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Oops, something went wrong.

0 comments on commit 25e2d10

Please sign in to comment.