|
|
|
|
|
================
|
|
|
|
|
|
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:
|
