5 :Author: David Goodger; open to all Docutils developers
6 :Contact: goodger@python.org
9 :Copyright: This document has been placed in the public domain.
11 .. _Docutils: http://docutils.sourceforge.net/
14 Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that
15 tend to stay in the shadows and don't bother anybody. Once in a while
16 new bugs are born. From time to time some bugs (new and old) crawl
17 out into the light and must be dealt with. Icky.
19 This document describes how to report a bug, and lists known bugs.
27 If you think you've discovered a bug, please read through these
28 guidelines before reporting it.
30 First, make sure it's a new bug:
32 * Please check the list of `known bugs`_ below and the `SourceForge
33 Bug Tracker`_ to see if it has already been reported.
35 * Are you using the very latest version of Docutils? The bug may have
36 already been fixed. Please get the latest version of Docutils from
37 CVS_ or from the `development snapshot`_ and check again. Even if
38 your bug has not been fixed, others probably have, and you're better
39 off with the most up-to-date code.
41 If you don't have time to check the latest snapshot, please report
42 the bug anyway. We'd rather tell you that it's already fixed than
43 miss reports of unfixed bugs.
45 * If Docutils does not behave the way you expect, look in the
46 documentation_ (don't forget the FAQ_!) and `mailing list archives`_
47 for evidence that it should behave the way you expect.
49 If you're not sure, please ask on the
50 docutils-users@lists.sourceforge.net [1]_ mailing list first.
52 If it's a new bug, the most important thing you can do is to write a
53 simple description and a recipe that reproduces the bug. Try to
54 create a minimal document that demonstrates the bug. The easier you
55 make it to understand and track down the bug, the more likely a fix
58 Now you're ready to write the bug report. Please include:
60 * A clear description of the bug. Describe how you expected Docutils
61 to behave, and contrast that with how it actually behaved. While
62 the bug may seem obvious to you, it may not be so obvious to someone
63 else, so it's best to avoid a guessing game.
65 * A complete description of the environment in which you reproduced
68 - Your operating system & version.
69 - The version of Python (``python -V``).
70 - The version of Docutils (use the "-V" option to most Docutils
72 - Any private modifications you made to Docutils.
73 - Anything else that could possibly be relevant. Err on the side
74 of too much information, rather than too little.
76 * A literal transcript of the *exact* command you ran, and the *exact*
77 output. Use the "--traceback" option to get a complete picture.
79 * The exact input and output files. Better to attach complete files
80 to your bug report than to include just a summary or excerpt.
82 * If you also want to include speculation as to the cause, and even a
83 patch to fix the bug, that would be great!
85 The best place to send your bug report is to the `SourceForge Bug
86 Tracker`_. That way, it won't be misplaced or forgotten. In fact, an
87 open bug report on SourceForge is a constant irritant that begs to be
92 (This section was inspired by the `Subversion project's`__ BUGS__
95 .. [1] Due to overwhelming amounts of spam, the
96 docutils-users@lists.sourceforge.net mailing list has been set up
97 for subscriber posting only. Non-subscribers who post to
98 docutils-users will receive a message with "Subject: Your message
99 to Docutils-users awaits moderator approval". Legitimate messages
100 are accepted and posted as soon as possible (a list administrator
101 must verify the message manually). If you'd like to subscribe to
102 docutils-users, please visit
103 <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
105 __ http://subversion.tigris.org/
106 __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
108 .. _CVS: http://sourceforge.net/cvs/?group_id=38414
109 .. _development snapshot: http://docutils.sf.net/#development-snapshot
110 .. _documentation: docs/
112 .. _mailing list archives: http://docutils.sf.net/#mailing-lists
113 .. _SourceForge Bug Tracker:
114 http://sourceforge.net/tracker/?group_id=38414&atid=422030
120 Also see the `SourceForge Bug Tracker`_.
122 * .. _empty csv-table:
124 When supplying an empty file for the csv-table directive, Docutils
125 crashes with a zero-division error. Example::
130 * _`Line numbers` in system messages are inconsistent in the parser.
132 - In text inserted by the "include" directive, errors are often not
133 reported with the correct "source" or "line" numbers. Perhaps all
134 Reporter calls need "source" and "line" keyword arguments.
135 Elements' .line assignments should be checked. (Assign to .source
136 too? Add a set_info method? To what?) There's a test in
137 test/test_parsers/test_rst/test_directives/test_include.py.
139 - Some line numbers in elements are not being set properly
140 (explicitly), just implicitly/automatically. See rev. 1.74 of
141 docutils/parsers/rst/states.py for an example of how to set.
145 Quite a few nodes are getting a "None" source attribute as well. In
146 particular, see the bodies of definition lists.
148 * .. _mislocated targets:
150 Explicit targets are sometimes mis-located. In particular, placing
151 a target before a section header puts the target at the end of the
152 previous section instead of the start of the next section. The code
153 in docutils.transforms.misc.ClassAttribute could be used to fix
154 this. (Reported by David Priest.)
156 * David Abrahams pointed out that _`doubly-indirect substitutions`
157 have a bug, but only when there's multiple references::
159 |substitute| my coke for gin
160 |substitute| you for my mum
161 at least I'll get my washing done
163 .. |substitute| replace:: |replace|
164 .. |replace| replace:: swap
166 This is tricky. Substitutions have to propagate back completely.
168 * .. _substitutions and references:
170 Another bug from David Abrahams (run with ``rst2html.py --traceback``)::
172 |substitution| and again a |substitution|.
174 .. |substitution| replace:: ref__
179 Change the references.Substitutions tranform's priority from 220 to
180 680, so it happens after reference resolution? Then we have to deal
181 with multiple IDs. Perhaps the Substitution transform should remove
182 all IDs from definitions after the first substitution reference is
185 * Footnote label "5" should be "4"::
187 $ rst2pseudoxml.py <<EOF
188 > ref [#abc]_ [#]_ [1]_ [#4]_
195 <document source="<stdin>">
198 <footnote_reference auto="1" id="id1" refid="abc">
201 <footnote_reference auto="1" id="id2" refid="id5">
204 <footnote_reference id="id3" refid="id6">
207 <footnote_reference auto="1" id="id4" refid="id7">
209 <footnote auto="1" backrefs="id1" id="abc" name="abc">
214 <footnote auto="1" backrefs="id2" id="id5" name="3">
219 <footnote backrefs="id3" id="id6" name="1">
224 <footnote auto="1" backrefs="id4" id="id7" name="4">
234 indent-tabs-mode: nil
235 sentence-end-double-space: t