BUGS.txt

   1 ================
   2  Docutils_ Bugs
   3 ================
   4
   5 :Author: David Goodger; open to all Docutils developers
   6 :Contact: goodger@python.org
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. _Docutils: http://docutils.sourceforge.net/
  12
  13
  14 Bugs in Docutils?!?  Yes, we do have a few.  Some are old-timers that
  15 tend to stay in the shadows and don't bother anybody.  Once in a while
  16 new bugs are born.  From time to time some bugs (new and old) crawl
  17 out into the light and must be dealt with.  Icky.
  18
  19 This document describes how to report a bug, and lists known bugs.
  20
  21 .. contents::
  22
  23
  24 How To Report A Bug
  25 ===================
  26
  27 If you think you've discovered a bug, please read through these
  28 guidelines before reporting it.
  29
  30 First, 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   CVS_ or from the `development snapshot`_ and check again.  Even if
  38   your bug has not been fixed, others probably have, and you're better
  39   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
  49 If you're not sure, please ask on the
  50 docutils-users@lists.sourceforge.net [1]_ mailing list first.
  51
  52 If it's a new bug, the most important thing you can do is to write a
  53 simple description and a recipe that reproduces the bug.  Try to
  54 create a minimal document that demonstrates the bug.  The easier you
  55 make it to understand and track down the bug, the more likely a fix
  56 will be.
  57
  58 Now you're ready to write the bug report.  Please include:
  59
  60 * A clear description of the bug.  Describe how you expected Docutils
  61   to behave, and contrast that with how it actually behaved.  While
  62   the bug may seem obvious to you, it may not be so obvious to someone
  63   else, so it's best to avoid a guessing game.
  64
  65 * A complete description of the environment in which you reproduced
  66   the bug:
  67
  68   - Your operating system & version.
  69   - The version of Python (``python -V``).
  70   - The version of Docutils (use the "-V" option to most Docutils
  71     front-end tools).
  72   - Any private modifications you made to Docutils.
  73   - Anything else that could possibly be relevant.  Err on the side
  74     of too much information, rather than too little.
  75
  76 * A literal transcript of the *exact* command you ran, and the *exact*
  77   output.  Use the "--traceback" option to get a complete picture.
  78
  79 * The exact input and output files.  Better to attach complete files
  80   to your bug report than to include just a summary or excerpt.
  81
  82 * If you also want to include speculation as to the cause, and even a
  83   patch to fix the bug, that would be great!
  84
  85 The best place to send your bug report is to the `SourceForge Bug
  86 Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
  87 open bug report on SourceForge is a constant irritant that begs to be
  88 squashed.
  89
  90 Thank you!
  91
  92 (This section was inspired by the `Subversion project's`__ BUGS__
  93 file.)
  94
  95 .. [1] Due to overwhelming amounts of spam, the
  96    docutils-users@lists.sourceforge.net mailing list has been set up
  97    for subscriber posting only.  Non-subscribers who post to
  98    docutils-users will receive a message with "Subject: Your message
  99    to Docutils-users awaits moderator approval".  Legitimate messages
 100    are accepted and posted as soon as possible (a list administrator
 101    must verify the message manually).  If you'd like to subscribe to
 102    docutils-users, please visit
 103    <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
 104
 105 __ http://subversion.tigris.org/
 106 __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
 107
 108 .. _CVS: http://sourceforge.net/cvs/?group_id=38414
 109 .. _development snapshot: http://docutils.sf.net/#development-snapshot
 110 .. _documentation: docs/
 111 .. _FAQ: FAQ.html
 112 .. _mailing list archives: http://docutils.sf.net/#mailing-lists
 113 .. _SourceForge Bug Tracker:
 114    http://sourceforge.net/tracker/?group_id=38414&atid=422030
 115
 116
 117 Known Bugs
 118 ==========
 119
 120 Also see the `SourceForge Bug Tracker`_.
 121
 122 * .. _unencoded stylesheet reference:
 123
 124   ``--stylesheet='foo&bar'`` causes an invalid stylesheet reference to
 125   be inserted in an HTML file, because the ``&`` isn't encoded as
 126   ``&amp;``.
 127
 128 * ``utils.relative_path()`` sometimes returns absolute _`paths on
 129   Windows` (like ``C:/test/foo.css``) where it could have chosen a
 130   relative path.
 131
 132   Furthermore, absolute pathnames are inserted verbatim, like
 133   ``href="C:/test/foo.css"`` instead of
 134   ``href="file:///C:/test/foo.css"``.
 135
 136   For details, see `this posting by Alan G. Isaac
 137   <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
 138
 139 * .. _empty csv-table:
 140
 141   When supplying an empty file for the csv-table directive, Docutils
 142   crashes with a zero-division error.  Example::
 143
 144       .. csv-table::
 145          :file: empty.txt
 146
 147 * _`Line numbers` in system messages are inconsistent in the parser.
 148
 149   - In text inserted by the "include" directive, errors are often not
 150     reported with the correct "source" or "line" numbers.  Perhaps all
 151     Reporter calls need "source" and "line" keyword arguments.
 152     Elements' .line assignments should be checked.  (Assign to .source
 153     too?  Add a set_info method?  To what?)  There's a test in
 154     test/test_parsers/test_rst/test_directives/test_include.py.
 155
 156   - Some line numbers in elements are not being set properly
 157     (explicitly), just implicitly/automatically.  See rev. 1.74 of
 158     docutils/parsers/rst/states.py for an example of how to set.
 159
 160 * .. _none source:
 161
 162   Quite a few nodes are getting a "None" source attribute as well.  In
 163   particular, see the bodies of definition lists.
 164
 165 * .. _mislocated targets:
 166
 167   Explicit targets are sometimes mis-located.  In particular, placing
 168   a target before a section header puts the target at the end of the
 169   previous section instead of the start of the next section.  The code
 170   in docutils.transforms.misc.ClassAttribute could be used to fix
 171   this.  (Reported by David Priest.)
 172
 173 * David Abrahams pointed out that _`doubly-indirect substitutions`
 174   have a bug, but only when there's multiple references::
 175
 176       |substitute| my coke for gin
 177       |substitute| you for my mum
 178       at least I'll get my washing done
 179
 180       .. |substitute| replace:: |replace|
 181       .. |replace| replace:: swap
 182
 183   This is tricky.  Substitutions have to propagate back completely.
 184
 185 * .. _substitutions and references:
 186
 187   Another bug from David Abrahams (run with ``rst2html.py --traceback``)::
 188
 189       |substitution| and again a |substitution|.
 190
 191       .. |substitution| replace:: ref__
 192
 193       __ a.html
 194       __ b.html
 195
 196   Change the references.Substitutions tranform's priority from 220 to
 197   680, so it happens after reference resolution?  Then we have to deal
 198   with multiple IDs.  Perhaps the Substitution transform should remove
 199   all IDs from definitions after the first substitution reference is
 200   processed.
 201
 202 * Footnote label "5" should be "4"::
 203
 204       $ rst2pseudoxml.py <<EOF
 205       > ref [#abc]_ [#]_ [1]_ [#4]_
 206       >
 207       > .. [#abc] footnote
 208       > .. [#] two
 209       > .. [1] one
 210       > .. [#4] four
 211       > EOF
 212       <document source="<stdin>">
 213           <paragraph>
 214               ref
 215               <footnote_reference auto="1" id="id1" refid="abc">
 216                   2
 217
 218               <footnote_reference auto="1" id="id2" refid="id5">
 219                   3
 220
 221               <footnote_reference id="id3" refid="id6">
 222                   1
 223
 224               <footnote_reference auto="1" id="id4" refid="id7">
 225                   5
 226           <footnote auto="1" backrefs="id1" id="abc" name="abc">
 227               <label>
 228                   2
 229               <paragraph>
 230                   footnote
 231           <footnote auto="1" backrefs="id2" id="id5" name="3">
 232               <label>
 233                   3
 234               <paragraph>
 235                   two
 236           <footnote backrefs="id3" id="id6" name="1">
 237               <label>
 238                   1
 239               <paragraph>
 240                   one
 241           <footnote auto="1" backrefs="id4" id="id7" name="4">
 242               <label>
 243                   5
 244               <paragraph>
 245                   four
 246
 247 \f
 248 ..
 249    Local Variables:
 250    mode: indented-text
 251    indent-tabs-mode: nil
 252    sentence-end-double-space: t
 253    fill-column: 70
 254    End: