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` and "source" in system messages are inconsistent.
 166
 167   - In text inserted by the "include" directive, errors are often not
 168     reported with the correct "source" or "line" numbers.
 169
 170     This is partially fixed in the commits from 2009-09-25 and 2009-10-28.
 171     The test in test/test_parsers/test_rst/test_directives/test_include.py
 172     works, but there are still plenty of system messages pointing to the
 173     wrong spot.
 174
 175   - Perhaps all Reporter calls need "source" and "line" keyword arguments?
 176
 177     Alternatively, give `document.reporter` access to the state machine
 178     instance `document.statemachine` and extract the "source" and "line"
 179     info from `statemachine.input_lines`.
 180     Except for special cases, there is even no need to call with "line":
 181     During parsing, `document.statemachine` knows the current line number.
 182     For system messages generated after the parsing is completed (i.e. by
 183     transforms or the writer) "line" info must be present in the doctree
 184     elements.
 185
 186   - Elements' .line assignments should be checked.  (Assign to .source
 187     too?  Add a set_info method?  To what?)
 188
 189     The "source" (and line number in the source) could either be added
 190     explicitely to the elements or determined from the “raw” line number by
 191     `document.statemachine.get_source_spot`.
 192
 193   - Some line numbers in elements are not being set properly
 194     (explicitly), just implicitly/automatically.  See rev. 1.74 of
 195     docutils/parsers/rst/states.py for an example of how to set.
 196
 197   - The line numbers of definition list items are wrong::
 198
 199         $ rst2pseudoxml.py --expose-internal-attribute line
 200         1
 201           2
 202           3
 203
 204         5
 205           6
 206           7
 207
 208         <document source="<stdin>">
 209             <definition_list>
 210                 <definition_list_item internal:line="3">
 211                     <term>
 212                         1
 213                     <definition>
 214                         <paragraph internal:line="2">
 215                             2
 216                             3
 217                 <definition_list_item internal:line="6">
 218                     <term>
 219                         5
 220                     <definition>
 221                         <paragraph internal:line="6">
 222                             6
 223                             7
 224
 225 * .. _none source:
 226
 227   Quite a few nodes are getting a "None" source attribute as well.  In
 228   particular, see the bodies of definition lists.
 229
 230 * Footnote label "5" should be "4" when processing the following
 231   input::
 232
 233       ref [#abc]_ [#]_ [1]_ [#4]_
 234
 235       .. [#abc] footnote
 236       .. [#] two
 237       .. [1] one
 238       .. [#4] four
 239
 240   Output::
 241
 242       <document source="<stdin>">
 243           <paragraph>
 244               ref
 245               <footnote_reference auto="1" ids="id1" refid="abc">
 246                   2
 247
 248               <footnote_reference auto="1" ids="id2" refid="id5">
 249                   3
 250
 251               <footnote_reference ids="id3" refid="id6">
 252                   1
 253
 254               <footnote_reference auto="1" ids="id4" refid="id7">
 255                   5
 256           <footnote auto="1" backrefs="id1" ids="abc" names="abc">
 257               <label>
 258                   2
 259               <paragraph>
 260                   footnote
 261           <footnote auto="1" backrefs="id2" ids="id5" names="3">
 262               <label>
 263                   3
 264               <paragraph>
 265                   two
 266           <footnote backrefs="id3" ids="id6" names="1">
 267               <label>
 268                   1
 269               <paragraph>
 270                   one
 271           <footnote auto="1" backrefs="id4" ids="id7" names="4">
 272               <label>
 273                   5
 274               <paragraph>
 275                   four
 276
 277 * IDs are based on names.  Explicit hyperlink targets have priority
 278   over implicit targets.  But if an explicit target comes after an
 279   implicit target with the same name, the ID of the first (implicit)
 280   target remains based on the implicit name.  Since HTML fragment
 281   identifiers based on the IDs, the first target keeps the name.  For
 282   example::
 283
 284       .. contents::
 285
 286       Section
 287       =======
 288
 289       .. _contents:
 290
 291       Subsection
 292       ----------
 293
 294       text with a reference to contents_ and section_
 295
 296       .. _section:
 297
 298       This paragraph is explicitly targeted with the name "section".
 299
 300   When processed to HTML, the 2 internal hyperlinks (to "contents" &
 301   "section") will work fine, but hyperlinks from outside the document
 302   using ``href="...#contents"`` and ``href="...#section"`` won't work.
 303   Such external links will connect to the implicit targets (table of
 304   contents and "Section" title) instead of the explicit targets
 305   ("Subsection" title and last paragraph).
 306
 307   Hyperlink targets with duplicate names should be assigned new IDs
 308   unrelated to the target names (i.e., "id"-prefix serial IDs).
 309
 310 * The "contents" ID of the local table of contents in
 311   ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
 312   the HTML output at
 313   ``test/functional/expected/standalone_rst_html4css1.html``.
 314
 315 * _`Blank first columns` in simple tables with explicit row separators
 316   silently swallow their input.  They should at least produce system
 317   error messages.  But, with explicit row separators, the meaning is
 318   unambiguous and ought to be supported::
 319
 320       ==============  ==========
 321       Table with row  separators
 322       ==============  ==========
 323                       and blank
 324       --------------  ----------
 325                       entries
 326       --------------  ----------
 327                       in first
 328       --------------  ----------
 329                       columns.
 330       ==============  ==========
 331
 332   Added a commented-out test case to
 333   test/test_parsers/test_rst/test_SimpleTableParser.py.
 334
 335 * _`Footnote references with hyperlink targets` cause a possibly
 336   invalid node tree and make the HTML writer crash::
 337
 338       $ rst2pseudoxml.py
 339       [1]_
 340
 341       .. _1: URI
 342       <document source="<stdin>">
 343           <paragraph>
 344               <footnote_reference ids="id1" refuri="URI">
 345                   1
 346           <target ids="id2" names="1" refuri="URI">
 347
 348 * Anonymous references have "name" attributes.  Should they?  Are they
 349   used?  See ``test/test_parsers/test_rst/test_inline_markup.py``.
 350
 351 * <reference> elements have a "name" attribute, not "names".  The
 352   attribute should be "names"; this is an inconsistency.
 353
 354 \f
 355 ..
 356    Local Variables:
 357    mode: indented-text
 358    indent-tabs-mode: nil
 359    sentence-end-double-space: t
 360    fill-column: 70
 361    End: