diff options
Diffstat (limited to 'docutils/BUGS.txt')
| -rw-r--r-- | docutils/BUGS.txt | 265 |
1 files changed, 0 insertions, 265 deletions
diff --git a/docutils/BUGS.txt b/docutils/BUGS.txt deleted file mode 100644 index 4e97af5a1..000000000 --- a/docutils/BUGS.txt +++ /dev/null @@ -1,265 +0,0 @@ -================ - Docutils_ Bugs -================ - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -: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 - CVS_ or from the `development 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@lists.sourceforge.net [1]_ 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 document that demonstrates the bug. The easier you -make it to understand and track down the bug, the more likely a fix -will be. - -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. 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.) - -.. [1] Due to overwhelming amounts of spam, the - docutils-users@lists.sourceforge.net mailing list has been set up - for subscriber posting only. Non-subscribers who post to - docutils-users will receive a message with "Subject: Your message - to Docutils-users awaits moderator approval". Legitimate messages - are accepted and posted as soon as possible (a list administrator - must verify the message manually). If you'd like to subscribe to - docutils-users, please visit - <http://lists.sourceforge.net/lists/listinfo/docutils-users>. - -__ http://subversion.tigris.org/ -__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup - -.. _CVS: http://sourceforge.net/cvs/?group_id=38414 -.. _development snapshot: http://docutils.sf.net/#development-snapshot -.. _documentation: docs/ -.. _FAQ: FAQ.html -.. _mailing list archives: http://docutils.sf.net/#mailing-lists -.. _SourceForge Bug Tracker: - http://sourceforge.net/tracker/?group_id=38414&atid=422030 - - -Known Bugs -========== - -Also see the `SourceForge Bug Tracker`_. - -* ``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` in system messages are inconsistent in the parser. - - - In text inserted by the "include" directive, errors are often not - reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need "source" and "line" keyword arguments. - Elements' .line assignments should be checked. (Assign to .source - too? Add a set_info method? To what?) There's a test in - test/test_parsers/test_rst/test_directives/test_include.py. - - - 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. - -* .. _none source: - - Quite a few nodes are getting a "None" source attribute as well. In - particular, see the bodies of definition lists. - -* David Abrahams pointed out that _`doubly-indirect substitutions` - have a bug, but only when there's multiple references:: - - |substitute| my coke for gin - |substitute| you for my mum - at least I'll get my washing done - - .. |substitute| replace:: |replace| - .. |replace| replace:: swap - - This is tricky. Substitutions have to propagate back completely. - -* .. _substitutions and references: - - Another bug from David Abrahams (run with ``rst2html.py --traceback``):: - - |substitution| and again a |substitution|. - - .. |substitution| replace:: ref__ - - __ a.html - __ b.html - - Change the references.Substitutions tranform's priority from 220 to - 680, so it happens after reference resolution? Then we have to deal - with multiple IDs. Perhaps the Substitution transform should remove - all IDs from definitions after the first substitution reference is - processed. - -* Footnote label "5" should be "4":: - - $ rst2pseudoxml.py <<EOF - > ref [#abc]_ [#]_ [1]_ [#4]_ - > - > .. [#abc] footnote - > .. [#] two - > .. [1] one - > .. [#4] four - > EOF - <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). - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |