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   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
  49 If you're not sure, please ask on the Docutils-users_ mailing list
  50 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 __ http://subversion.tigris.org/
  96 __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
  97
  98 .. _CVS: http://sourceforge.net/cvs/?group_id=38414
  99 .. _repository: docs/dev/repository.html
 100 .. _snapshot: http://docutils.sourceforge.net/#download
 101 .. _documentation: docs/
 102 .. _FAQ: FAQ.html
 103 .. _mailing list archives: http://docutils.sf.net/#mailing-lists
 104 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 105 .. _SourceForge Bug Tracker:
 106    http://sourceforge.net/tracker/?group_id=38414&atid=422030
 107
 108
 109 Known Bugs
 110 ==========
 111
 112 Also see the `SourceForge Bug Tracker`_.
 113
 114 * ``utils.relative_path()`` sometimes returns absolute _`paths on
 115   Windows` (like ``C:/test/foo.css``) where it could have chosen a
 116   relative path.
 117
 118   Furthermore, absolute pathnames are inserted verbatim, like
 119   ``href="C:/test/foo.css"`` instead of
 120   ``href="file:///C:/test/foo.css"``.
 121
 122   For details, see `this posting by Alan G. Isaac
 123   <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
 124
 125 * _`Line numbers` in system messages are inconsistent in the parser.
 126
 127   - In text inserted by the "include" directive, errors are often not
 128     reported with the correct "source" or "line" numbers.  Perhaps all
 129     Reporter calls need "source" and "line" keyword arguments.
 130     Elements' .line assignments should be checked.  (Assign to .source
 131     too?  Add a set_info method?  To what?)  There's a test in
 132     test/test_parsers/test_rst/test_directives/test_include.py.
 133
 134   - Some line numbers in elements are not being set properly
 135     (explicitly), just implicitly/automatically.  See rev. 1.74 of
 136     docutils/parsers/rst/states.py for an example of how to set.
 137
 138 * .. _none source:
 139
 140   Quite a few nodes are getting a "None" source attribute as well.  In
 141   particular, see the bodies of definition lists.
 142
 143 * David Abrahams pointed out that _`doubly-indirect substitutions`
 144   have a bug, but only when there's multiple references::
 145
 146       |substitute| my coke for gin
 147       |substitute| you for my mum
 148       at least I'll get my washing done
 149
 150       .. |substitute| replace:: |replace|
 151       .. |replace| replace:: swap
 152
 153   This is tricky.  Substitutions have to propagate back completely.
 154
 155 * .. _substitutions and references:
 156
 157   Another bug from David Abrahams (run with ``rst2html.py --traceback``)::
 158
 159       |substitution| and again a |substitution|.
 160
 161       .. |substitution| replace:: ref__
 162
 163       __ a.html
 164       __ b.html
 165
 166   Change the references.Substitutions tranform's priority from 220 to
 167   680, so it happens after reference resolution?  Then we have to deal
 168   with multiple IDs.  Perhaps the Substitution transform should remove
 169   all IDs from definitions after the first substitution reference is
 170   processed.
 171
 172 * Footnote label "5" should be "4"::
 173
 174       $ rst2pseudoxml.py <<EOF
 175       > ref [#abc]_ [#]_ [1]_ [#4]_
 176       >
 177       > .. [#abc] footnote
 178       > .. [#] two
 179       > .. [1] one
 180       > .. [#4] four
 181       > EOF
 182       <document source="<stdin>">
 183           <paragraph>
 184               ref
 185               <footnote_reference auto="1" ids="id1" refid="abc">
 186                   2
 187
 188               <footnote_reference auto="1" ids="id2" refid="id5">
 189                   3
 190
 191               <footnote_reference ids="id3" refid="id6">
 192                   1
 193
 194               <footnote_reference auto="1" ids="id4" refid="id7">
 195                   5
 196           <footnote auto="1" backrefs="id1" ids="abc" names="abc">
 197               <label>
 198                   2
 199               <paragraph>
 200                   footnote
 201           <footnote auto="1" backrefs="id2" ids="id5" names="3">
 202               <label>
 203                   3
 204               <paragraph>
 205                   two
 206           <footnote backrefs="id3" ids="id6" names="1">
 207               <label>
 208                   1
 209               <paragraph>
 210                   one
 211           <footnote auto="1" backrefs="id4" ids="id7" names="4">
 212               <label>
 213                   5
 214               <paragraph>
 215                   four
 216
 217 * IDs are based on names.  Explicit hyperlink targets have priority
 218   over implicit targets.  But if an explicit target comes after an
 219   implicit target with the same name, the ID of the first (implicit)
 220   target remains based on the implicit name.  Since HTML fragment
 221   identifiers based on the IDs, the first target keeps the name.  For
 222   example::
 223
 224       .. contents::
 225
 226       Section
 227       =======
 228
 229       .. _contents:
 230
 231       Subsection
 232       ----------
 233
 234       text with a reference to contents_ and section_
 235
 236       .. _section:
 237
 238       This paragraph is explicitly targeted with the name "section".
 239
 240   When processed to HTML, the 2 internal hyperlinks (to "contents" &
 241   "section") will work fine, but hyperlinks from outside the document
 242   using ``href="...#contents"`` and ``href="...#section"`` won't work.
 243   Such external links will connect to the implicit targets (table of
 244   contents and "Section" title) instead of the explicit targets
 245   ("Subsection" title and last paragraph).
 246
 247   Hyperlink targets with duplicate names should be assigned new IDs
 248   unrelated to the target names (i.e., "id"-prefix serial IDs).
 249
 250 \f
 251 ..
 252    Local Variables:
 253    mode: indented-text
 254    indent-tabs-mode: nil
 255    sentence-end-double-space: t
 256    fill-column: 70
 257    End: