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 ---------------------------------------------------------------------
  53
  54 If it's a new bug, the most important thing you can do is to write a
  55 simple description and a recipe that reproduces the bug.  Try to
  56 create a `minimal example`_ that demonstrates the bug.  The easier you
  57 make it to understand and track down the bug, the more likely a fix
  58 will be.
  59
  60 .. sidebar:: minimal example
  61
  62   .. _minimal example:
  63
  64   A minimal example is an example which is as small as possible. These
  65   examples are much easier to understand than long examples.
  66
  67   To construct an example which is as small as possible, the rule is
  68   quite simple: *remove anything which is not necessary*.
  69
  70   See also: `LaTeX FAQ`__, `Lilypond Documentation`__, minimalbeispiel.de__
  71
  72   __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
  73   __ http://lilypond.org/doc/v2.9/Documentation/user/lilypond/Minimal-examples
  74   __ http://www.minimalbeispiel.de/mini-en.html
  75
  76 Now you're ready to write the bug report.  Please include:
  77
  78 * A clear description of the bug.  Describe how you expected Docutils
  79   to behave, and contrast that with how it actually behaved.  While
  80   the bug may seem obvious to you, it may not be so obvious to someone
  81   else, so it's best to avoid a guessing game.
  82
  83 * A complete description of the environment in which you reproduced
  84   the bug:
  85
  86   - Your operating system & version.
  87   - The version of Python (``python -V``).
  88   - The version of Docutils (use the "-V" option to most Docutils
  89     front-end tools).
  90   - Any private modifications you made to Docutils.
  91   - Anything else that could possibly be relevant.  Err on the side
  92     of too much information, rather than too little.
  93
  94 * A literal transcript of the *exact* command you ran, and the *exact*
  95   output.  Use the "--traceback" option to get a complete picture.
  96
  97 * The exact input and output files.  Create a `minimal example`_
  98   of the failing behaviour — it is better to attach complete files
  99   to your bug report than to include just a summary or excerpt.
 100
 101 * If you also want to include speculation as to the cause, and even a
 102   patch to fix the bug, that would be great!
 103
 104 The best place to send your bug report is to the `SourceForge Bug
 105 Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
 106 open bug report on SourceForge is a constant irritant that begs to be
 107 squashed.
 108
 109 Thank you!
 110
 111 (This section was inspired by the `Subversion project's`__ BUGS__
 112 file.)
 113
 114 __ http://subversion.tigris.org/
 115 __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
 116
 117 .. _CVS: http://sourceforge.net/cvs/?group_id=38414
 118 .. _repository: docs/dev/repository.html
 119 .. _snapshot: http://docutils.sourceforge.net/#download
 120 .. _documentation: docs/
 121 .. _FAQ: FAQ.html
 122 .. _mailing list archives: http://docutils.sf.net/#mailing-lists
 123 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 124 .. _SourceForge Bug Tracker:
 125    http://sourceforge.net/tracker/?group_id=38414&atid=422030
 126
 127
 128 Known Bugs
 129 ==========
 130
 131 Also see the `SourceForge Bug Tracker`_.
 132
 133 * The HTML writer generates invalid XHTML for _`centered images with
 134   targets`::
 135
 136       .. image:: example.png
 137          :align: center
 138          :target: http://docutils.sourceforge.net/
 139
 140   This results in ``<a><div><img /></div></a>``, which is invalid.
 141
 142 * .. _error reporting:
 143
 144   Calling rst2s5.py with a non-existent theme (``--theme
 145   does_not_exist``) or a non-existent language (``--language zz``)
 146   causes exceptions.  Such errors should be handled more gracefully.
 147
 148 * The "stylesheet" setting (a URL, to be used verbatim) should be
 149   allowed to be combined with "embed_stylesheet".  The stylesheet data
 150   should be read in using urllib.  There was an assumption that a
 151   stylesheet to be embedded should exist as a file on the local
 152   system, and only the "stylesheet_path" setting should be used.
 153
 154 * ``utils.relative_path()`` sometimes returns absolute _`paths on
 155   Windows` (like ``C:/test/foo.css``) where it could have chosen a
 156   relative path.
 157
 158   Furthermore, absolute pathnames are inserted verbatim, like
 159   ``href="C:/test/foo.css"`` instead of
 160   ``href="file:///C:/test/foo.css"``.
 161
 162   For details, see `this posting by Alan G. Isaac
 163   <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
 164
 165 * _`Line numbers` in system messages are inconsistent in the parser.
 166
 167   - In text inserted by the "include" directive, errors are often not
 168     reported with the correct "source" or "line" numbers.  Perhaps all
 169     Reporter calls need "source" and "line" keyword arguments.
 170     Elements' .line assignments should be checked.  (Assign to .source
 171     too?  Add a set_info method?  To what?)  There's a test in
 172     test/test_parsers/test_rst/test_directives/test_include.py.
 173
 174     This is partially fixed in the commit on 2009-09-25, although the
 175     commented-out test case in the abovementioned file does still fail.
 176
 177   - Some line numbers in elements are not being set properly
 178     (explicitly), just implicitly/automatically.  See rev. 1.74 of
 179     docutils/parsers/rst/states.py for an example of how to set.
 180
 181   - The line numbers of definition list items are wrong::
 182
 183         $ rst2pseudoxml.py --expose-internal-attribute line
 184         1
 185           2
 186           3
 187
 188         5
 189           6
 190           7
 191         <document source="<stdin>">
 192             <definition_list>
 193                 <definition_list_item internal:line="3">
 194                     <term>
 195                         1
 196                     <definition>
 197                         <paragraph internal:line="2">
 198                             2
 199                             3
 200                 <definition_list_item internal:line="6">
 201                     <term>
 202                         5
 203                     <definition>
 204                         <paragraph internal:line="6">
 205                             6
 206                             7
 207
 208 * .. _none source:
 209
 210   Quite a few nodes are getting a "None" source attribute as well.  In
 211   particular, see the bodies of definition lists.
 212
 213 * Footnote label "5" should be "4" when processing the following
 214   input::
 215
 216       ref [#abc]_ [#]_ [1]_ [#4]_
 217
 218       .. [#abc] footnote
 219       .. [#] two
 220       .. [1] one
 221       .. [#4] four
 222
 223   Output::
 224
 225       <document source="<stdin>">
 226           <paragraph>
 227               ref
 228               <footnote_reference auto="1" ids="id1" refid="abc">
 229                   2
 230
 231               <footnote_reference auto="1" ids="id2" refid="id5">
 232                   3
 233
 234               <footnote_reference ids="id3" refid="id6">
 235                   1
 236
 237               <footnote_reference auto="1" ids="id4" refid="id7">
 238                   5
 239           <footnote auto="1" backrefs="id1" ids="abc" names="abc">
 240               <label>
 241                   2
 242               <paragraph>
 243                   footnote
 244           <footnote auto="1" backrefs="id2" ids="id5" names="3">
 245               <label>
 246                   3
 247               <paragraph>
 248                   two
 249           <footnote backrefs="id3" ids="id6" names="1">
 250               <label>
 251                   1
 252               <paragraph>
 253                   one
 254           <footnote auto="1" backrefs="id4" ids="id7" names="4">
 255               <label>
 256                   5
 257               <paragraph>
 258                   four
 259
 260 * IDs are based on names.  Explicit hyperlink targets have priority
 261   over implicit targets.  But if an explicit target comes after an
 262   implicit target with the same name, the ID of the first (implicit)
 263   target remains based on the implicit name.  Since HTML fragment
 264   identifiers based on the IDs, the first target keeps the name.  For
 265   example::
 266
 267       .. contents::
 268
 269       Section
 270       =======
 271
 272       .. _contents:
 273
 274       Subsection
 275       ----------
 276
 277       text with a reference to contents_ and section_
 278
 279       .. _section:
 280
 281       This paragraph is explicitly targeted with the name "section".
 282
 283   When processed to HTML, the 2 internal hyperlinks (to "contents" &
 284   "section") will work fine, but hyperlinks from outside the document
 285   using ``href="...#contents"`` and ``href="...#section"`` won't work.
 286   Such external links will connect to the implicit targets (table of
 287   contents and "Section" title) instead of the explicit targets
 288   ("Subsection" title and last paragraph).
 289
 290   Hyperlink targets with duplicate names should be assigned new IDs
 291   unrelated to the target names (i.e., "id"-prefix serial IDs).
 292
 293 * The "contents" ID of the local table of contents in
 294   ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
 295   the HTML output at
 296   ``test/functional/expected/standalone_rst_html4css1.html``.
 297
 298 * _`Blank first columns` in simple tables with explicit row separators
 299   silently swallow their input.  They should at least produce system
 300   error messages.  But, with explicit row separators, the meaning is
 301   unambiguous and ought to be supported::
 302
 303       ==============  ==========
 304       Table with row  separators
 305       ==============  ==========
 306                       and blank
 307       --------------  ----------
 308                       entries
 309       --------------  ----------
 310                       in first
 311       --------------  ----------
 312                       columns.
 313       ==============  ==========
 314
 315   Added a commented-out test case to
 316   test/test_parsers/test_rst/test_SimpleTableParser.py.
 317
 318 * _`Footnote references with hyperlink targets` cause a possibly
 319   invalid node tree and make the HTML writer crash::
 320
 321       $ rst2pseudoxml.py
 322       [1]_
 323
 324       .. _1: URI
 325       <document source="<stdin>">
 326           <paragraph>
 327               <footnote_reference ids="id1" refuri="URI">
 328                   1
 329           <target ids="id2" names="1" refuri="URI">
 330
 331 * Anonymous references have "name" attributes.  Should they?  Are they
 332   used?  See ``test/test_parsers/test_rst/test_inline_markup.py``.
 333
 334 * <reference> elements have a "name" attribute, not "names".  The
 335   attribute should be "names"; this is an inconsistency.
 336
 337 \f
 338 ..
 339    Local Variables:
 340    mode: indented-text
 341    indent-tabs-mode: nil
 342    sentence-end-double-space: t
 343    fill-column: 70
 344    End: