Author: | David Goodger; open to all Docutils developers |
---|---|
Contact: | goodger@python.org |
Date: | 2005-04-25 03:12:00 +0200 (Mon, 25 Apr 2005) |
Revision: | 3252 |
Copyright: | This document has been placed in the public domain. |
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.
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:
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>. |
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.
Line numbers in system messages are inconsistent in the parser.
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.
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).