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 * The HTML writer generates invalid XHTML for _`centered images with
 115   targets`::
 116
 117       .. image:: example.png
 118          :align: center
 119          :target: http://docutils.sourceforge.net/
 120
 121   This results in ``<a><div><img /></div></a>``, which is invalid.
 122
 123 * .. _error reporting:
 124
 125   Calling rst2s5.py with a non-existent theme (``--theme
 126   does_not_exist``) or a non-existent language (``--language zz``)
 127   causes exceptions.  Such errors should be handled more gracefully.
 128
 129 * There's a problem with _`hyperlink references in substitutions`::
 130
 131       |rst| is cool!
 132
 133       .. |rst| replace:: reStructuredText_
 134
 135       .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 136
 137   There is a preferred alternative::
 138
 139      |rst|_ is cool!
 140
 141       .. |rst| replace:: reStructuredText
 142       .. _rst: http://docutils.sourceforge.net/rst.html
 143
 144   This only works for the case where the entire substitution is a
 145   reference, not when the reference is embedded as part of the
 146   substitution.
 147
 148   The problem pattern has never been tested for, perhaps because of
 149   the alternative.  Unit tests should be added.
 150
 151   This was not a bug in Docutils 0.3.7 (`reference
 152   <http://thread.gmane.org/gmane.text.docutils.user/2997/focus=2997>`__).
 153
 154 * The "stylesheet" setting (a URL, to be used verbatim) should be
 155   allowed to be combined with "embed_stylesheet".  The stylesheet data
 156   should be read in using urllib.  There was an assumption that a
 157   stylesheet to be embedded should exist as a file on the local
 158   system, and only the "stylesheet_path" setting should be used.
 159
 160 * ``utils.relative_path()`` sometimes returns absolute _`paths on
 161   Windows` (like ``C:/test/foo.css``) where it could have chosen a
 162   relative path.
 163
 164   Furthermore, absolute pathnames are inserted verbatim, like
 165   ``href="C:/test/foo.css"`` instead of
 166   ``href="file:///C:/test/foo.css"``.
 167
 168   For details, see `this posting by Alan G. Isaac
 169   <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
 170
 171 * _`Line numbers` in system messages are inconsistent in the parser.
 172
 173   - In text inserted by the "include" directive, errors are often not
 174     reported with the correct "source" or "line" numbers.  Perhaps all
 175     Reporter calls need "source" and "line" keyword arguments.
 176     Elements' .line assignments should be checked.  (Assign to .source
 177     too?  Add a set_info method?  To what?)  There's a test in
 178     test/test_parsers/test_rst/test_directives/test_include.py.
 179
 180   - Some line numbers in elements are not being set properly
 181     (explicitly), just implicitly/automatically.  See rev. 1.74 of
 182     docutils/parsers/rst/states.py for an example of how to set.
 183
 184   - The line numbers of definition list items are wrong::
 185
 186         $ rst2pseudoxml.py --expose-internal-attribute line
 187         1
 188           2
 189           3
 190
 191         5
 192           6
 193           7
 194         <document source="<stdin>">
 195             <definition_list>
 196                 <definition_list_item internal:line="3">
 197                     <term>
 198                         1
 199                     <definition>
 200                         <paragraph internal:line="2">
 201                             2
 202                             3
 203                 <definition_list_item internal:line="6">
 204                     <term>
 205                         5
 206                     <definition>
 207                         <paragraph internal:line="6">
 208                             6
 209                             7
 210
 211 * .. _none source:
 212
 213   Quite a few nodes are getting a "None" source attribute as well.  In
 214   particular, see the bodies of definition lists.
 215
 216 * Footnote label "5" should be "4" when processing the following
 217   input::
 218
 219       ref [#abc]_ [#]_ [1]_ [#4]_
 220
 221       .. [#abc] footnote
 222       .. [#] two
 223       .. [1] one
 224       .. [#4] four
 225
 226   Output::
 227
 228       <document source="<stdin>">
 229           <paragraph>
 230               ref
 231               <footnote_reference auto="1" ids="id1" refid="abc">
 232                   2
 233
 234               <footnote_reference auto="1" ids="id2" refid="id5">
 235                   3
 236
 237               <footnote_reference ids="id3" refid="id6">
 238                   1
 239
 240               <footnote_reference auto="1" ids="id4" refid="id7">
 241                   5
 242           <footnote auto="1" backrefs="id1" ids="abc" names="abc">
 243               <label>
 244                   2
 245               <paragraph>
 246                   footnote
 247           <footnote auto="1" backrefs="id2" ids="id5" names="3">
 248               <label>
 249                   3
 250               <paragraph>
 251                   two
 252           <footnote backrefs="id3" ids="id6" names="1">
 253               <label>
 254                   1
 255               <paragraph>
 256                   one
 257           <footnote auto="1" backrefs="id4" ids="id7" names="4">
 258               <label>
 259                   5
 260               <paragraph>
 261                   four
 262
 263 * IDs are based on names.  Explicit hyperlink targets have priority
 264   over implicit targets.  But if an explicit target comes after an
 265   implicit target with the same name, the ID of the first (implicit)
 266   target remains based on the implicit name.  Since HTML fragment
 267   identifiers based on the IDs, the first target keeps the name.  For
 268   example::
 269
 270       .. contents::
 271
 272       Section
 273       =======
 274
 275       .. _contents:
 276
 277       Subsection
 278       ----------
 279
 280       text with a reference to contents_ and section_
 281
 282       .. _section:
 283
 284       This paragraph is explicitly targeted with the name "section".
 285
 286   When processed to HTML, the 2 internal hyperlinks (to "contents" &
 287   "section") will work fine, but hyperlinks from outside the document
 288   using ``href="...#contents"`` and ``href="...#section"`` won't work.
 289   Such external links will connect to the implicit targets (table of
 290   contents and "Section" title) instead of the explicit targets
 291   ("Subsection" title and last paragraph).
 292
 293   Hyperlink targets with duplicate names should be assigned new IDs
 294   unrelated to the target names (i.e., "id"-prefix serial IDs).
 295
 296 * The "contents" ID of the local table of contents in
 297   ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
 298   the HTML output at
 299   ``test/functional/expected/standalone_rst_html4css1.html``.
 300
 301 * _`Blank first columns` in simple tables with explicit row separators
 302   silently swallow their input.  They should at least produce system
 303   error messages.  But, with explicit row separators, the meaning is
 304   unambiguous and ought to be supported::
 305
 306       ==============  ==========
 307       Table with row  separators
 308       ==============  ==========
 309                       and blank
 310       --------------  ----------
 311                       entries
 312       --------------  ----------
 313                       in first
 314       --------------  ----------
 315                       columns.
 316       ==============  ==========
 317
 318   Added a commented-out test case to
 319   test/test_parsers/test_rst/test_SimpleTableParser.py.
 320
 321 * _`Footnote references with hyperlink targets` cause a possibly
 322   invalid node tree and make the HTML writer crash::
 323
 324       $ rst2pseudoxml.py
 325       [1]_
 326
 327       .. _1: URI
 328       <document source="<stdin>">
 329           <paragraph>
 330               <footnote_reference ids="id1" refuri="URI">
 331                   1
 332           <target ids="id2" names="1" refuri="URI">
 333
 334 * Anonymous references have "name" attributes.  Should they?  Are they
 335   used?  See ``test/test_parsers/test_rst/test_inline_markup.py``.
 336
 337 * <reference> elements have a "name" attribute, not "names".  The
 338   attribute should be "names"; this is an inconsistency.
 339
 340 * Setting the _`halt level` should implicitly set the report level to
 341   at most the halt level; otherwise Docutils might halt without
 342   providing a descriptive error message::
 343
 344       ~ $ rst2pseudoxml.py --halt=1 --no-traceback
 345       2. foo
 346       Exiting due to level-1 (INFO) system message.
 347
 348 \f
 349 ..
 350    Local Variables:
 351    mode: indented-text
 352    indent-tabs-mode: nil
 353    sentence-end-double-space: t
 354    fill-column: 70
 355    End: