5
:Author: David Goodger; open to all Docutils developers
6
:Contact: goodger@python.org
7
:Date: $Date: 2005-12-29 00:48:48 +0100 (Thu, 29 Dec 2005) $
8
:Revision: $Revision: 4233 $
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
the repository_ or from the current snapshot_ and check again. Even
38
if your bug has not been fixed, others probably have, and you're
39
better 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 Docutils-users_ mailing list
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
__ http://subversion.tigris.org/
96
__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
98
.. _CVS: http://sourceforge.net/cvs/?group_id=38414
99
.. _repository: docs/dev/repository.html
100
.. _snapshot: http://docutils.sourceforge.net/#download
101
.. _documentation: docs/
103
.. _mailing list archives: http://docutils.sf.net/#mailing-lists
104
.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
105
.. _SourceForge Bug Tracker:
106
http://sourceforge.net/tracker/?group_id=38414&atid=422030
112
Also see the `SourceForge Bug Tracker`_.
114
* The "stylesheet" setting (a URL, to be used verbatim) should be
115
allowed to be combined with "embed_stylesheet". The stylesheet data
116
should be read in using urllib. There was an assumption that a
117
stylesheet to be embedded should exist as a file on the local
118
system, and only the "stylesheet_path" setting should be used.
120
* ``utils.relative_path()`` sometimes returns absolute _`paths on
121
Windows` (like ``C:/test/foo.css``) where it could have chosen a
124
Furthermore, absolute pathnames are inserted verbatim, like
125
``href="C:/test/foo.css"`` instead of
126
``href="file:///C:/test/foo.css"``.
128
For details, see `this posting by Alan G. Isaac
129
<http://article.gmane.org/gmane.text.docutils.user/1569>`_.
131
* _`Line numbers` in system messages are inconsistent in the parser.
133
- In text inserted by the "include" directive, errors are often not
134
reported with the correct "source" or "line" numbers. Perhaps all
135
Reporter calls need "source" and "line" keyword arguments.
136
Elements' .line assignments should be checked. (Assign to .source
137
too? Add a set_info method? To what?) There's a test in
138
test/test_parsers/test_rst/test_directives/test_include.py.
140
- Some line numbers in elements are not being set properly
141
(explicitly), just implicitly/automatically. See rev. 1.74 of
142
docutils/parsers/rst/states.py for an example of how to set.
146
Quite a few nodes are getting a "None" source attribute as well. In
147
particular, see the bodies of definition lists.
149
* Footnote label "5" should be "4" when processing the following
152
ref [#abc]_ [#]_ [1]_ [#4]_
161
<document source="<stdin>">
164
<footnote_reference auto="1" ids="id1" refid="abc">
167
<footnote_reference auto="1" ids="id2" refid="id5">
170
<footnote_reference ids="id3" refid="id6">
173
<footnote_reference auto="1" ids="id4" refid="id7">
175
<footnote auto="1" backrefs="id1" ids="abc" names="abc">
180
<footnote auto="1" backrefs="id2" ids="id5" names="3">
185
<footnote backrefs="id3" ids="id6" names="1">
190
<footnote auto="1" backrefs="id4" ids="id7" names="4">
196
* IDs are based on names. Explicit hyperlink targets have priority
197
over implicit targets. But if an explicit target comes after an
198
implicit target with the same name, the ID of the first (implicit)
199
target remains based on the implicit name. Since HTML fragment
200
identifiers based on the IDs, the first target keeps the name. For
213
text with a reference to contents_ and section_
217
This paragraph is explicitly targeted with the name "section".
219
When processed to HTML, the 2 internal hyperlinks (to "contents" &
220
"section") will work fine, but hyperlinks from outside the document
221
using ``href="...#contents"`` and ``href="...#section"`` won't work.
222
Such external links will connect to the implicit targets (table of
223
contents and "Section" title) instead of the explicit targets
224
("Subsection" title and last paragraph).
226
Hyperlink targets with duplicate names should be assigned new IDs
227
unrelated to the target names (i.e., "id"-prefix serial IDs).
229
* The "contents" ID of the local table of contents in
230
``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
232
``test/functional/expected/standalone_rst_html4css1.html``.
234
* _`Blank first columns` in simple tables with explicit row separators
235
silently swallow their input. They should at least produce system
236
error messages. But, with explicit row separators, the meaning is
237
unambiguous and ought to be supported::
239
============== ==========
240
Table with row separators
241
============== ==========
243
-------------- ----------
245
-------------- ----------
247
-------------- ----------
249
============== ==========
251
Added a commented-out test case to
252
test/test_parsers/test_rst/test_SimpleTableParser.py.
254
* _`Footnote references with hyperlink targets` cause a possibly
255
invalid node tree and make the HTML writer crash::
261
<document source="<stdin>">
263
<footnote_reference ids="id1" refuri="URI">
265
<target ids="id2" names="1" refuri="URI">
267
* Anonymous references have "name" attributes. Should they? Are they
268
used? See ``test/test_parsers/test_rst/test_inline_markup.py``.
270
* <reference> elements have a "name" attribute, not "names". The
271
attribute should be "names"; this is an inconsistency.
277
indent-tabs-mode: nil
278
sentence-end-double-space: t
added
removed
BUGS.txt
