|
|
================ |
|
|
Docutils_ Bugs |
|
|
================ |
|
|
|
|
|
:Author: David Goodger; open to all Docutils developers |
|
|
:Contact: goodger@python.org |
|
|
:Date: $Date: 2017-06-09 13:02:35 +0200 (Fr, 09 Jun 2017) $ |
|
|
:Revision: $Revision: 8103 $ |
|
|
: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 |
|
|
the repository_ or from the current 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_ 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 example`_ that demonstrates the bug. The easier you |
|
|
make it to understand and track down the bug, the more likely a fix |
|
|
will be. |
|
|
|
|
|
.. _minimal example: |
|
|
|
|
|
.. sidebar:: minimal example |
|
|
|
|
|
A `minimal working example` is a complete example which is as as small and |
|
|
simple as possible. It should be complete and working, so that |
|
|
|
|
|
* you cannot accidentally omit information important to diagnosing |
|
|
the problem and |
|
|
* the person responding can just copy-and-paste the code to try it out. |
|
|
|
|
|
To construct an example which is as small as possible, the rule |
|
|
quite simple: *remove/leave out anything which is not necessary*. |
|
|
|
|
|
See also: `What is a minimal working example?`__, `LaTeX FAQ`__ |
|
|
|
|
|
__ http://www.minimalbeispiel.de/mini-en.html |
|
|
__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl |
|
|
|
|
|
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. Create a `minimal example`_ |
|
|
of the failing behaviour — it is 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.) |
|
|
|
|
|
__ http://subversion.tigris.org/ |
|
|
__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup |
|
|
|
|
|
.. _repository: docs/dev/repository.html |
|
|
.. _snapshot: http://docutils.sourceforge.net/#download |
|
|
.. _documentation: docs/ |
|
|
.. _FAQ: FAQ.html |
|
|
.. _mailing list archives: http://docutils.sf.net/#mailing-lists |
|
|
.. _Docutils-users: docs/user/mailing-lists.html#docutils-users |
|
|
.. _SourceForge Bug Tracker: |
|
|
http://sourceforge.net/p/docutils/bugs/ |
|
|
|
|
|
|
|
|
Known Bugs |
|
|
========== |
|
|
|
|
|
Also see the `SourceForge Bug Tracker`_. |
|
|
|
|
|
* .. _error reporting: |
|
|
|
|
|
Calling rst2s5.py with a non-existent theme (``--theme |
|
|
does_not_exist``) |
|
|
causes exceptions. Such errors should be handled more gracefully. |
|
|
|
|
|
* The "stylesheet" setting (a URL, to be used verbatim) should be |
|
|
allowed to be combined with "embed_stylesheet". The stylesheet data |
|
|
should be read in using urllib. There was an assumption that a |
|
|
stylesheet to be embedded should exist as a file on the local |
|
|
system, and only the "stylesheet_path" setting should be used. |
|
|
|
|
|
* ``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"``. |
|
|
|
|
|
.. gmane web interface is down. |
|
|
TODO: find this article in the Sourceforge mail archives |
|
|
For details, see `this posting by Alan G. Isaac |
|
|
<http://article.gmane.org/gmane.text.docutils.user/1569>`_. |
|
|
|
|
|
* Footnote label "5" should be "4" when processing the following |
|
|
input:: |
|
|
|
|
|
ref [#abc]_ [#]_ [1]_ [#4]_ |
|
|
|
|
|
.. [#abc] footnote |
|
|
.. [#] two |
|
|
.. [1] one |
|
|
.. [#4] four |
|
|
|
|
|
Output:: |
|
|
|
|
|
<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). |
|
|
|
|
|
* The "contents" ID of the local table of contents in |
|
|
``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in |
|
|
the HTML output at |
|
|
``test/functional/expected/standalone_rst_html4css1.html``. |
|
|
|
|
|
* _`Blank first columns` in simple tables with explicit row separators |
|
|
silently swallow their input. They should at least produce system |
|
|
error messages. But, with explicit row separators, the meaning is |
|
|
unambiguous and ought to be supported:: |
|
|
|
|
|
============== ========== |
|
|
Table with row separators |
|
|
============== ========== |
|
|
and blank |
|
|
-------------- ---------- |
|
|
entries |
|
|
-------------- ---------- |
|
|
in first |
|
|
-------------- ---------- |
|
|
columns. |
|
|
============== ========== |
|
|
|
|
|
Added a commented-out test case to |
|
|
test/test_parsers/test_rst/test_SimpleTableParser.py. |
|
|
|
|
|
* _`Footnote references with hyperlink targets` cause a possibly |
|
|
invalid node tree and make the HTML writer crash:: |
|
|
|
|
|
$ rst2pseudoxml.py |
|
|
[1]_ |
|
|
|
|
|
.. _1: URI |
|
|
<document source="<stdin>"> |
|
|
<paragraph> |
|
|
<footnote_reference ids="id1" refuri="URI"> |
|
|
1 |
|
|
<target ids="id2" names="1" refuri="URI"> |
|
|
|
|
|
* Anonymous references have "name" attributes. Should they? Are they |
|
|
used? See ``test/test_parsers/test_rst/test_inline_markup.py``. |
|
|
|
|
|
* <reference> elements have a "name" attribute, not "names". The |
|
|
attribute should be "names"; this is an inconsistency. |
|
|
|
|
|
|
|
|
.. |
|
|
Local Variables: |
|
|
mode: indented-text |
|
|
indent-tabs-mode: nil |
|
|
sentence-end-double-space: t |
|
|
fill-column: 70 |
|
|
End:
|
|
|
|
