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 * .. _error reporting:
 134
 135   Calling rst2s5.py with a non-existent theme (``--theme
 136   does_not_exist``)
 137   causes exceptions.  Such errors should be handled more gracefully.
 138
 139 * The "stylesheet" setting (a URL, to be used verbatim) should be
 140   allowed to be combined with "embed_stylesheet".  The stylesheet data
 141   should be read in using urllib.  There was an assumption that a
 142   stylesheet to be embedded should exist as a file on the local
 143   system, and only the "stylesheet_path" setting should be used.
 144
 145 * ``utils.relative_path()`` sometimes returns absolute _`paths on
 146   Windows` (like ``C:/test/foo.css``) where it could have chosen a
 147   relative path.
 148
 149   Furthermore, absolute pathnames are inserted verbatim, like
 150   ``href="C:/test/foo.css"`` instead of
 151   ``href="file:///C:/test/foo.css"``.
 152
 153   For details, see `this posting by Alan G. Isaac
 154   <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
 155
 156 * Footnote label "5" should be "4" when processing the following
 157   input::
 158
 159       ref [#abc]_ [#]_ [1]_ [#4]_
 160
 161       .. [#abc] footnote
 162       .. [#] two
 163       .. [1] one
 164       .. [#4] four
 165
 166   Output::
 167
 168       <document source="<stdin>">
 169           <paragraph>
 170               ref
 171               <footnote_reference auto="1" ids="id1" refid="abc">
 172                   2
 173
 174               <footnote_reference auto="1" ids="id2" refid="id5">
 175                   3
 176
 177               <footnote_reference ids="id3" refid="id6">
 178                   1
 179
 180               <footnote_reference auto="1" ids="id4" refid="id7">
 181                   5
 182           <footnote auto="1" backrefs="id1" ids="abc" names="abc">
 183               <label>
 184                   2
 185               <paragraph>
 186                   footnote
 187           <footnote auto="1" backrefs="id2" ids="id5" names="3">
 188               <label>
 189                   3
 190               <paragraph>
 191                   two
 192           <footnote backrefs="id3" ids="id6" names="1">
 193               <label>
 194                   1
 195               <paragraph>
 196                   one
 197           <footnote auto="1" backrefs="id4" ids="id7" names="4">
 198               <label>
 199                   5
 200               <paragraph>
 201                   four
 202
 203 * IDs are based on names.  Explicit hyperlink targets have priority
 204   over implicit targets.  But if an explicit target comes after an
 205   implicit target with the same name, the ID of the first (implicit)
 206   target remains based on the implicit name.  Since HTML fragment
 207   identifiers based on the IDs, the first target keeps the name.  For
 208   example::
 209
 210       .. contents::
 211
 212       Section
 213       =======
 214
 215       .. _contents:
 216
 217       Subsection
 218       ----------
 219
 220       text with a reference to contents_ and section_
 221
 222       .. _section:
 223
 224       This paragraph is explicitly targeted with the name "section".
 225
 226   When processed to HTML, the 2 internal hyperlinks (to "contents" &
 227   "section") will work fine, but hyperlinks from outside the document
 228   using ``href="...#contents"`` and ``href="...#section"`` won't work.
 229   Such external links will connect to the implicit targets (table of
 230   contents and "Section" title) instead of the explicit targets
 231   ("Subsection" title and last paragraph).
 232
 233   Hyperlink targets with duplicate names should be assigned new IDs
 234   unrelated to the target names (i.e., "id"-prefix serial IDs).
 235
 236 * The "contents" ID of the local table of contents in
 237   ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
 238   the HTML output at
 239   ``test/functional/expected/standalone_rst_html4css1.html``.
 240
 241 * _`Blank first columns` in simple tables with explicit row separators
 242   silently swallow their input.  They should at least produce system
 243   error messages.  But, with explicit row separators, the meaning is
 244   unambiguous and ought to be supported::
 245
 246       ==============  ==========
 247       Table with row  separators
 248       ==============  ==========
 249                       and blank
 250       --------------  ----------
 251                       entries
 252       --------------  ----------
 253                       in first
 254       --------------  ----------
 255                       columns.
 256       ==============  ==========
 257
 258   Added a commented-out test case to
 259   test/test_parsers/test_rst/test_SimpleTableParser.py.
 260
 261 * _`Footnote references with hyperlink targets` cause a possibly
 262   invalid node tree and make the HTML writer crash::
 263
 264       $ rst2pseudoxml.py
 265       [1]_
 266
 267       .. _1: URI
 268       <document source="<stdin>">
 269           <paragraph>
 270               <footnote_reference ids="id1" refuri="URI">
 271                   1
 272           <target ids="id2" names="1" refuri="URI">
 273
 274 * Anonymous references have "name" attributes.  Should they?  Are they
 275   used?  See ``test/test_parsers/test_rst/test_inline_markup.py``.
 276
 277 * <reference> elements have a "name" attribute, not "names".  The
 278   attribute should be "names"; this is an inconsistency.
 279
 280 \f
 281 ..
 282    Local Variables:
 283    mode: indented-text
 284    indent-tabs-mode: nil
 285    sentence-end-double-space: t
 286    fill-column: 70
 287    End: