1 .. include:: docs/header0.txt
7 :Author: David Goodger; open to all Docutils developers
8 :Contact: goodger@python.org
11 :Copyright: This document has been placed in the public domain.
13 .. _Docutils: https://docutils.sourceforge.io/
16 Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that
17 tend to stay in the shadows and don't bother anybody. Once in a while
18 new bugs are born. From time to time some bugs (new and old) crawl
19 out into the light and must be dealt with. Icky.
21 This document describes how to report a bug, and lists known bugs.
29 If you think you've discovered a bug, please read through these
30 guidelines before reporting it.
32 First, make sure it's a new bug:
34 * Please check the list of `known bugs`_ below and the `SourceForge
35 Bug Tracker`_ to see if it has already been reported.
37 * Are you using the very latest version of Docutils? The bug may have
38 already been fixed. Please get the latest version of Docutils from
39 the repository_ or from the current snapshot_ and check again. Even
40 if your bug has not been fixed, others probably have, and you're
41 better off with the most up-to-date code.
43 If you don't have time to check the latest snapshot, please report
44 the bug anyway. We'd rather tell you that it's already fixed than
45 miss reports of unfixed bugs.
47 * If Docutils does not behave the way you expect, look in the
48 documentation_ (don't forget the FAQ_!) and `mailing list archives`_
49 for evidence that it should behave the way you expect.
51 If you're not sure, please ask on the Docutils-users_ mailing list
54 ---------------------------------------------------------------------
56 If it's a new bug, the most important thing you can do is to write a
57 simple description and a recipe that reproduces the bug. Try to
58 create a `minimal example`_ that demonstrates the bug. The easier you
59 make it to understand and track down the bug, the more likely a fix
64 .. sidebar:: minimal example
66 A `minimal working example` is a complete example which is as as small and
67 simple as possible. It should be complete and working, so that
69 * you cannot accidentally omit information important to diagnosing
71 * the person responding can just copy-and-paste the code to try it out.
73 To construct an example which is as small as possible, the rule
74 quite simple: *remove/leave out anything which is not necessary*.
76 See also: `What is a minimal working example?`__, `LaTeX FAQ`__
78 __ http://www.minimalbeispiel.de/mini-en.html
79 __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
81 Now you're ready to write the bug report. Please include:
83 * A clear description of the bug. Describe how you expected Docutils
84 to behave, and contrast that with how it actually behaved. While
85 the bug may seem obvious to you, it may not be so obvious to someone
86 else, so it's best to avoid a guessing game.
88 * A complete description of the environment in which you reproduced
91 - Your operating system & version.
92 - The version of Python (``python -V``).
93 - The version of Docutils (use the "-V" option to most Docutils
95 - Any private modifications you made to Docutils.
96 - Anything else that could possibly be relevant. Err on the side
97 of too much information, rather than too little.
99 * A literal transcript of the *exact* command you ran, and the *exact*
100 output. Use the "--traceback" option to get a complete picture.
102 * The exact input and output files. Create a `minimal example`_
103 of the failing behaviour — it is better to attach complete files
104 to your bug report than to include just a summary or excerpt.
106 * If you also want to include speculation as to the cause, and even a
107 patch to fix the bug, that would be great!
109 The best place to send your bug report is to the `SourceForge Bug
110 Tracker`_. That way, it won't be misplaced or forgotten. In fact, an
111 open bug report on SourceForge is a constant irritant that begs to be
116 (This section was inspired by the `Subversion project's`__ BUGS__
119 __ http://subversion.tigris.org/
120 __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
122 .. _repository: docs/dev/repository.html
123 .. _snapshot: https://docutils.sourceforge.io/#download
124 .. _documentation: docs/
126 .. _mailing list archives: https://docutils.sourceforge.io/#mailing-lists
127 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
128 .. _SourceForge Bug Tracker:
129 https://sourceforge.net/p/docutils/bugs/
135 Also see the `SourceForge Bug Tracker`_.
137 * .. _error reporting:
139 Calling rst2s5 with a non-existent theme (``--theme
141 causes exceptions. Such errors should be handled more gracefully.
143 * The "stylesheet" setting (a URL, to be used verbatim) should be
144 allowed to be combined with "embed_stylesheet". The stylesheet data
145 should be read in using urllib. There was an assumption that a
146 stylesheet to be embedded should exist as a file on the local
147 system, and only the "stylesheet_path" setting should be used.
149 * ``utils.relative_path()`` sometimes returns absolute _`paths on
150 Windows` (like ``C:/test/foo.css``) where it could have chosen a
153 Furthermore, absolute pathnames are inserted verbatim, like
154 ``href="C:/test/foo.css"`` instead of
155 ``href="file:///C:/test/foo.css"``.
157 .. gmane web interface is down.
158 TODO: find this article in the Sourceforge mail archives
159 For details, see `this posting by Alan G. Isaac
160 <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
162 * Footnote label "5" should be "4" when processing the following
165 ref [#abc]_ [#]_ [1]_ [#4]_
174 <document source="<stdin>">
177 <footnote_reference auto="1" ids="id1" refid="abc">
180 <footnote_reference auto="1" ids="id2" refid="id5">
183 <footnote_reference ids="id3" refid="id6">
186 <footnote_reference auto="1" ids="id4" refid="id7">
188 <footnote auto="1" backrefs="id1" ids="abc" names="abc">
193 <footnote auto="1" backrefs="id2" ids="id5" names="3">
198 <footnote backrefs="id3" ids="id6" names="1">
203 <footnote auto="1" backrefs="id4" ids="id7" names="4">
209 * IDs are based on names. Explicit hyperlink targets have priority
210 over implicit targets. But if an explicit target comes after an
211 implicit target with the same name, the ID of the first (implicit)
212 target remains based on the implicit name. Since HTML fragment
213 identifiers are based on the IDs, the first target keeps the name.
226 text with a reference to contents_ and section_
230 This paragraph is explicitly targeted with the name "section".
232 When processed to HTML, the 2 internal hyperlinks (to "contents" &
233 "section") will work fine, but hyperlinks from outside the document
234 using ``href="...#contents"`` and ``href="...#section"`` won't work.
235 Such external links will connect to the implicit targets (table of
236 contents and "Section" title) instead of the explicit targets
237 ("Subsection" title and last paragraph).
239 Hyperlink targets with duplicate names should be assigned new IDs
240 unrelated to the target names (i.e., "id"-prefix serial IDs).
242 * The "contents" ID of the local table of contents in
243 ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
245 ``test/functional/expected/standalone_rst_html4css1.html``.
247 * _`Blank first columns` in simple tables with explicit row separators
248 silently swallow their input. They should at least produce system
249 error messages. But, with explicit row separators, the meaning is
250 unambiguous and ought to be supported::
252 ============== ==========
253 Table with row separators
254 ============== ==========
256 -------------- ----------
258 -------------- ----------
260 -------------- ----------
262 ============== ==========
264 Added a commented-out test case to
265 test/test_parsers/test_rst/test_SimpleTableParser.py.
267 * _`Footnote references with hyperlink targets` cause a possibly
268 invalid node tree and make the HTML writer crash::
274 <document source="<stdin>">
276 <footnote_reference ids="id1" refuri="URI">
278 <target ids="id2" names="1" refuri="URI">
280 * Anonymous references have "name" attributes. Should they? Are they
281 used? See ``test/test_parsers/test_rst/test_inline_markup.py``.
283 * <reference> elements have a "name" attribute, not "names". The
284 attribute should be "names"; this is an inconsistency.
290 indent-tabs-mode: nil
291 sentence-end-double-space: t