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