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