BUGS.txt 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291
  1. ================
  2. Docutils_ Bugs
  3. ================
  4. :Author: David Goodger; open to all Docutils developers
  5. :Contact: goodger@python.org
  6. :Date: $Date: 2017-06-09 13:02:35 +0200 (Fr, 09 Jun 2017) $
  7. :Revision: $Revision: 8103 $
  8. :Copyright: This document has been placed in the public domain.
  9. .. _Docutils: http://docutils.sourceforge.net/
  10. Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that
  11. tend to stay in the shadows and don't bother anybody. Once in a while
  12. new bugs are born. From time to time some bugs (new and old) crawl
  13. out into the light and must be dealt with. Icky.
  14. This document describes how to report a bug, and lists known bugs.
  15. .. contents::
  16. How To Report A Bug
  17. ===================
  18. If you think you've discovered a bug, please read through these
  19. guidelines before reporting it.
  20. First, make sure it's a new bug:
  21. * Please check the list of `known bugs`_ below and the `SourceForge
  22. Bug Tracker`_ to see if it has already been reported.
  23. * Are you using the very latest version of Docutils? The bug may have
  24. already been fixed. Please get the latest version of Docutils from
  25. the repository_ or from the current snapshot_ and check again. Even
  26. if your bug has not been fixed, others probably have, and you're
  27. better off with the most up-to-date code.
  28. If you don't have time to check the latest snapshot, please report
  29. the bug anyway. We'd rather tell you that it's already fixed than
  30. miss reports of unfixed bugs.
  31. * If Docutils does not behave the way you expect, look in the
  32. documentation_ (don't forget the FAQ_!) and `mailing list archives`_
  33. for evidence that it should behave the way you expect.
  34. If you're not sure, please ask on the Docutils-users_ mailing list
  35. first.
  36. ---------------------------------------------------------------------
  37. If it's a new bug, the most important thing you can do is to write a
  38. simple description and a recipe that reproduces the bug. Try to
  39. create a `minimal example`_ that demonstrates the bug. The easier you
  40. make it to understand and track down the bug, the more likely a fix
  41. will be.
  42. .. _minimal example:
  43. .. sidebar:: minimal example
  44. A `minimal working example` is a complete example which is as as small and
  45. simple as possible. It should be complete and working, so that
  46. * you cannot accidentally omit information important to diagnosing
  47. the problem and
  48. * the person responding can just copy-and-paste the code to try it out.
  49. To construct an example which is as small as possible, the rule
  50. quite simple: *remove/leave out anything which is not necessary*.
  51. See also: `What is a minimal working example?`__, `LaTeX FAQ`__
  52. __ http://www.minimalbeispiel.de/mini-en.html
  53. __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
  54. Now you're ready to write the bug report. Please include:
  55. * A clear description of the bug. Describe how you expected Docutils
  56. to behave, and contrast that with how it actually behaved. While
  57. the bug may seem obvious to you, it may not be so obvious to someone
  58. else, so it's best to avoid a guessing game.
  59. * A complete description of the environment in which you reproduced
  60. the bug:
  61. - Your operating system & version.
  62. - The version of Python (``python -V``).
  63. - The version of Docutils (use the "-V" option to most Docutils
  64. front-end tools).
  65. - Any private modifications you made to Docutils.
  66. - Anything else that could possibly be relevant. Err on the side
  67. of too much information, rather than too little.
  68. * A literal transcript of the *exact* command you ran, and the *exact*
  69. output. Use the "--traceback" option to get a complete picture.
  70. * The exact input and output files. Create a `minimal example`_
  71. of the failing behaviour — it is better to attach complete files
  72. to your bug report than to include just a summary or excerpt.
  73. * If you also want to include speculation as to the cause, and even a
  74. patch to fix the bug, that would be great!
  75. The best place to send your bug report is to the `SourceForge Bug
  76. Tracker`_. That way, it won't be misplaced or forgotten. In fact, an
  77. open bug report on SourceForge is a constant irritant that begs to be
  78. squashed.
  79. Thank you!
  80. (This section was inspired by the `Subversion project's`__ BUGS__
  81. file.)
  82. __ http://subversion.tigris.org/
  83. __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
  84. .. _repository: docs/dev/repository.html
  85. .. _snapshot: http://docutils.sourceforge.net/#download
  86. .. _documentation: docs/
  87. .. _FAQ: FAQ.html
  88. .. _mailing list archives: http://docutils.sf.net/#mailing-lists
  89. .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
  90. .. _SourceForge Bug Tracker:
  91. http://sourceforge.net/p/docutils/bugs/
  92. Known Bugs
  93. ==========
  94. Also see the `SourceForge Bug Tracker`_.
  95. * .. _error reporting:
  96. Calling rst2s5.py with a non-existent theme (``--theme
  97. does_not_exist``)
  98. causes exceptions. Such errors should be handled more gracefully.
  99. * The "stylesheet" setting (a URL, to be used verbatim) should be
  100. allowed to be combined with "embed_stylesheet". The stylesheet data
  101. should be read in using urllib. There was an assumption that a
  102. stylesheet to be embedded should exist as a file on the local
  103. system, and only the "stylesheet_path" setting should be used.
  104. * ``utils.relative_path()`` sometimes returns absolute _`paths on
  105. Windows` (like ``C:/test/foo.css``) where it could have chosen a
  106. relative path.
  107. Furthermore, absolute pathnames are inserted verbatim, like
  108. ``href="C:/test/foo.css"`` instead of
  109. ``href="file:///C:/test/foo.css"``.
  110. .. gmane web interface is down.
  111. TODO: find this article in the Sourceforge mail archives
  112. For details, see `this posting by Alan G. Isaac
  113. <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
  114. * Footnote label "5" should be "4" when processing the following
  115. input::
  116. ref [#abc]_ [#]_ [1]_ [#4]_
  117. .. [#abc] footnote
  118. .. [#] two
  119. .. [1] one
  120. .. [#4] four
  121. Output::
  122. <document source="<stdin>">
  123. <paragraph>
  124. ref
  125. <footnote_reference auto="1" ids="id1" refid="abc">
  126. 2
  127. <footnote_reference auto="1" ids="id2" refid="id5">
  128. 3
  129. <footnote_reference ids="id3" refid="id6">
  130. 1
  131. <footnote_reference auto="1" ids="id4" refid="id7">
  132. 5
  133. <footnote auto="1" backrefs="id1" ids="abc" names="abc">
  134. <label>
  135. 2
  136. <paragraph>
  137. footnote
  138. <footnote auto="1" backrefs="id2" ids="id5" names="3">
  139. <label>
  140. 3
  141. <paragraph>
  142. two
  143. <footnote backrefs="id3" ids="id6" names="1">
  144. <label>
  145. 1
  146. <paragraph>
  147. one
  148. <footnote auto="1" backrefs="id4" ids="id7" names="4">
  149. <label>
  150. 5
  151. <paragraph>
  152. four
  153. * IDs are based on names. Explicit hyperlink targets have priority
  154. over implicit targets. But if an explicit target comes after an
  155. implicit target with the same name, the ID of the first (implicit)
  156. target remains based on the implicit name. Since HTML fragment
  157. identifiers based on the IDs, the first target keeps the name. For
  158. example::
  159. .. contents::
  160. Section
  161. =======
  162. .. _contents:
  163. Subsection
  164. ----------
  165. text with a reference to contents_ and section_
  166. .. _section:
  167. This paragraph is explicitly targeted with the name "section".
  168. When processed to HTML, the 2 internal hyperlinks (to "contents" &
  169. "section") will work fine, but hyperlinks from outside the document
  170. using ``href="...#contents"`` and ``href="...#section"`` won't work.
  171. Such external links will connect to the implicit targets (table of
  172. contents and "Section" title) instead of the explicit targets
  173. ("Subsection" title and last paragraph).
  174. Hyperlink targets with duplicate names should be assigned new IDs
  175. unrelated to the target names (i.e., "id"-prefix serial IDs).
  176. * The "contents" ID of the local table of contents in
  177. ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
  178. the HTML output at
  179. ``test/functional/expected/standalone_rst_html4css1.html``.
  180. * _`Blank first columns` in simple tables with explicit row separators
  181. silently swallow their input. They should at least produce system
  182. error messages. But, with explicit row separators, the meaning is
  183. unambiguous and ought to be supported::
  184. ============== ==========
  185. Table with row separators
  186. ============== ==========
  187. and blank
  188. -------------- ----------
  189. entries
  190. -------------- ----------
  191. in first
  192. -------------- ----------
  193. columns.
  194. ============== ==========
  195. Added a commented-out test case to
  196. test/test_parsers/test_rst/test_SimpleTableParser.py.
  197. * _`Footnote references with hyperlink targets` cause a possibly
  198. invalid node tree and make the HTML writer crash::
  199. $ rst2pseudoxml.py
  200. [1]_
  201. .. _1: URI
  202. <document source="<stdin>">
  203. <paragraph>
  204. <footnote_reference ids="id1" refuri="URI">
  205. 1
  206. <target ids="id2" names="1" refuri="URI">
  207. * Anonymous references have "name" attributes. Should they? Are they
  208. used? See ``test/test_parsers/test_rst/test_inline_markup.py``.
  209. * <reference> elements have a "name" attribute, not "names". The
  210. attribute should be "names"; this is an inconsistency.
  211. ..
  212. Local Variables:
  213. mode: indented-text
  214. indent-tabs-mode: nil
  215. sentence-end-double-space: t
  216. fill-column: 70
  217. End: