docutils/BUGS.txt

   1 .. include:: docs/header0.txt
   2
   3 ================
   4  Docutils_ Bugs
   5 ================
   6
   7 :Author: David Goodger; open to all Docutils developers
   8 :Contact: goodger@python.org
   9 :Date: $Date$
  10 :Revision: $Revision$
  11 :Copyright: This document has been placed in the public domain.
  12
  13 .. _Docutils: https://docutils.sourceforge.io/
  14
  15
  16 Bugs in Docutils?!?  Yes, we do have a few.  Some are old-timers that
  17 tend to stay in the shadows and don't bother anybody.  Once in a while
  18 new bugs are born.  From time to time some bugs (new and old) crawl
  19 out into the light and must be dealt with.  Icky.
  20
  21 This document describes how to report a bug, and lists known bugs.
  22
  23 .. contents::
  24
  25
  26 How To Report A Bug
  27 ===================
  28
  29 If you think you've discovered a bug, please read through these
  30 guidelines before reporting it.
  31
  32 First, make sure it's a new bug:
  33
  34 * Please check the list of `known bugs`_ below and the `SourceForge
  35   Bug Tracker`_ to see if it has already been reported.
  36
  37 * Are you using the very latest version of Docutils?  The bug may have
  38   already been fixed.  Please get the latest version of Docutils from
  39   the repository_ or from the current snapshot_ and check again.  Even
  40   if your bug has not been fixed, others probably have, and you're
  41   better off with the most up-to-date code.
  42
  43   If you don't have time to check the latest snapshot, please report
  44   the bug anyway.  We'd rather tell you that it's already fixed than
  45   miss reports of unfixed bugs.
  46
  47 * If Docutils does not behave the way you expect, look in the
  48   documentation_ (don't forget the FAQ_!) and `mailing list archives`_
  49   for evidence that it should behave the way you expect.
  50
  51 If you're not sure, please ask on the Docutils-users_ mailing list
  52 first.
  53
  54 ---------------------------------------------------------------------
  55
  56 If it's a new bug, the most important thing you can do is to write a
  57 simple description and a recipe that reproduces the bug.  Try to
  58 create a `minimal example`_ that demonstrates the bug.  The easier you
  59 make it to understand and track down the bug, the more likely a fix
  60 will be.
  61
  62 .. _minimal example:
  63
  64 .. sidebar:: minimal example
  65
  66   A `minimal working example` is a complete example which is as as small and
  67   simple as possible. It should be complete and working, so that
  68
  69   * you cannot accidentally omit information important to diagnosing
  70     the problem and
  71   * the person responding can just copy-and-paste the code to try it out.
  72
  73   To construct an example which is as small as possible, the rule
  74   quite simple: *remove/leave out anything which is not necessary*.
  75
  76   See also: `What is a minimal working example?`__, `LaTeX FAQ`__
  77
  78   __ http://www.minimalbeispiel.de/mini-en.html
  79   __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
  80
  81 Now you're ready to write the bug report.  Please include:
  82
  83 * A clear description of the bug.  Describe how you expected Docutils
  84   to behave, and contrast that with how it actually behaved.  While
  85   the bug may seem obvious to you, it may not be so obvious to someone
  86   else, so it's best to avoid a guessing game.
  87
  88 * A complete description of the environment in which you reproduced
  89   the bug:
  90
  91   - Your operating system & version.
  92   - The version of Python (``python -V``).
  93   - The version of Docutils (use the "-V" option to most Docutils
  94     front-end tools).
  95   - Any private modifications you made to Docutils.
  96   - Anything else that could possibly be relevant.  Err on the side
  97     of too much information, rather than too little.
  98
  99 * A literal transcript of the *exact* command you ran, and the *exact*
 100   output.  Use the "--traceback" option to get a complete picture.
 101
 102 * The exact input and output files.  Create a `minimal example`_
 103   of the failing behaviour — it is better to attach complete files
 104   to your bug report than to include just a summary or excerpt.
 105
 106 * If you also want to include speculation as to the cause, and even a
 107   patch to fix the bug, that would be great!
 108
 109 The best place to send your bug report is to the `SourceForge Bug
 110 Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
 111 open bug report on SourceForge is a constant irritant that begs to be
 112 squashed.
 113
 114 Thank you!
 115
 116 (This section was inspired by the `Subversion project's`__ BUGS__
 117 file.)
 118
 119 __ http://subversion.tigris.org/
 120 __ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
 121
 122 .. _repository: docs/dev/repository.html
 123 .. _snapshot: https://docutils.sourceforge.io/#download
 124 .. _documentation: docs/
 125 .. _FAQ: FAQ.html
 126 .. _mailing list archives: https://docutils.sourceforge.io/#mailing-lists
 127 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 128 .. _SourceForge Bug Tracker:
 129    https://sourceforge.net/p/docutils/bugs/
 130
 131
 132 Known Bugs
 133 ==========
 134
 135 Also see the `SourceForge Bug Tracker`_.
 136
 137 * .. _error reporting:
 138
 139   Calling rst2s5 with a non-existent theme (``--theme
 140   does_not_exist``)
 141   causes exceptions.  Such errors should be handled more gracefully.
 142
 143 * The "stylesheet" setting (a URL, to be used verbatim) should be
 144   allowed to be combined with "embed_stylesheet".  The stylesheet data
 145   should be read in using urllib.  There was an assumption that a
 146   stylesheet to be embedded should exist as a file on the local
 147   system, and only the "stylesheet_path" setting should be used.
 148
 149 * ``utils.relative_path()`` sometimes returns absolute _`paths on
 150   Windows` (like ``C:/test/foo.css``) where it could have chosen a
 151   relative path.
 152
 153   Furthermore, absolute pathnames are inserted verbatim, like
 154   ``href="C:/test/foo.css"`` instead of
 155   ``href="file:///C:/test/foo.css"``.
 156
 157   .. gmane web interface is down.
 158      TODO: find this article in the Sourceforge mail archives
 159      For details, see `this posting by Alan G. Isaac
 160      <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
 161
 162 * Footnote label "5" should be "4" when processing the following
 163   input::
 164
 165       ref [#abc]_ [#]_ [1]_ [#4]_
 166
 167       .. [#abc] footnote
 168       .. [#] two
 169       .. [1] one
 170       .. [#4] four
 171
 172   Output::
 173
 174       <document source="<stdin>">
 175           <paragraph>
 176               ref
 177               <footnote_reference auto="1" ids="id1" refid="abc">
 178                   2
 179
 180               <footnote_reference auto="1" ids="id2" refid="id5">
 181                   3
 182
 183               <footnote_reference ids="id3" refid="id6">
 184                   1
 185
 186               <footnote_reference auto="1" ids="id4" refid="id7">
 187                   5
 188           <footnote auto="1" backrefs="id1" ids="abc" names="abc">
 189               <label>
 190                   2
 191               <paragraph>
 192                   footnote
 193           <footnote auto="1" backrefs="id2" ids="id5" names="3">
 194               <label>
 195                   3
 196               <paragraph>
 197                   two
 198           <footnote backrefs="id3" ids="id6" names="1">
 199               <label>
 200                   1
 201               <paragraph>
 202                   one
 203           <footnote auto="1" backrefs="id4" ids="id7" names="4">
 204               <label>
 205                   5
 206               <paragraph>
 207                   four
 208
 209 * IDs are based on names.  Explicit hyperlink targets have priority
 210   over implicit targets.  But if an explicit target comes after an
 211   implicit target with the same name, the ID of the first (implicit)
 212   target remains based on the implicit name.  Since HTML fragment
 213   identifiers are based on the IDs, the first target keeps the name.
 214   For example::
 215
 216       .. contents::
 217
 218       Section
 219       =======
 220
 221       .. _contents:
 222
 223       Subsection
 224       ----------
 225
 226       text with a reference to contents_ and section_
 227
 228       .. _section:
 229
 230       This paragraph is explicitly targeted with the name "section".
 231
 232   When processed to HTML, the 2 internal hyperlinks (to "contents" &
 233   "section") will work fine, but hyperlinks from outside the document
 234   using ``href="...#contents"`` and ``href="...#section"`` won't work.
 235   Such external links will connect to the implicit targets (table of
 236   contents and "Section" title) instead of the explicit targets
 237   ("Subsection" title and last paragraph).
 238
 239   Hyperlink targets with duplicate names should be assigned new IDs
 240   unrelated to the target names (i.e., "id"-prefix serial IDs).
 241
 242 * The "contents" ID of the local table of contents in
 243   ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
 244   the HTML output at
 245   ``test/functional/expected/standalone_rst_html4css1.html``.
 246
 247 * _`Blank first columns` in simple tables with explicit row separators
 248   silently swallow their input.  They should at least produce system
 249   error messages.  But, with explicit row separators, the meaning is
 250   unambiguous and ought to be supported::
 251
 252       ==============  ==========
 253       Table with row  separators
 254       ==============  ==========
 255                       and blank
 256       --------------  ----------
 257                       entries
 258       --------------  ----------
 259                       in first
 260       --------------  ----------
 261                       columns.
 262       ==============  ==========
 263
 264   Added a commented-out test case to
 265   test/test_parsers/test_rst/test_SimpleTableParser.py.
 266
 267 * _`Footnote references with hyperlink targets` cause a possibly
 268   invalid node tree and make the HTML writer crash::
 269
 270       $ rst2pseudoxml
 271       [1]_
 272
 273       .. _1: URI
 274       <document source="<stdin>">
 275           <paragraph>
 276               <footnote_reference ids="id1" refuri="URI">
 277                   1
 278           <target ids="id2" names="1" refuri="URI">
 279
 280 * Anonymous references have "name" attributes.  Should they?  Are they
 281   used?  See ``test/test_parsers/test_rst/test_inline_markup.py``.
 282
 283 * <reference> elements have a "name" attribute, not "names".  The
 284   attribute should be "names"; this is an inconsistency.
 285
 286
 287 ..\f Emacs settings
 288
 289    Local Variables:
 290    mode: indented-text
 291    mode: rst
 292    indent-tabs-mode: nil
 293    sentence-end-double-space: t
 294    fill-column: 70
 295    End: