Fixed another bug with emacs section titles, where

[docutils.git] / BUGS.txt

================
 Docutils_ Bugs
================

:Author: David Goodger; open to all Docutils developers
:Contact: goodger@python.org
:Date: $Date$
:Revision: $Revision$
:Copyright: This document has been placed in the public domain.

.. _Docutils: http://docutils.sourceforge.net/


Bugs in Docutils?!?  Yes, we do have a few.  Some are old-timers that
tend to stay in the shadows and don't bother anybody.  Once in a while
new bugs are born.  From time to time some bugs (new and old) crawl
out into the light and must be dealt with.  Icky.

This document describes how to report a bug, and lists known bugs.

.. contents::


How To Report A Bug
===================

If you think you've discovered a bug, please read through these
guidelines before reporting it.

First, make sure it's a new bug:

* Please check the list of `known bugs`_ below and the `SourceForge
  Bug Tracker`_ to see if it has already been reported.

* Are you using the very latest version of Docutils?  The bug may have
  already been fixed.  Please get the latest version of Docutils from
  CVS_ or from the `development snapshot`_ and check again.  Even if
  your bug has not been fixed, others probably have, and you're better
  off with the most up-to-date code.

  If you don't have time to check the latest snapshot, please report
  the bug anyway.  We'd rather tell you that it's already fixed than
  miss reports of unfixed bugs.

* If Docutils does not behave the way you expect, look in the
  documentation_ (don't forget the FAQ_!) and `mailing list archives`_
  for evidence that it should behave the way you expect.

If you're not sure, please ask on the
docutils-users@lists.sourceforge.net [1]_ mailing list first.

If it's a new bug, the most important thing you can do is to write a
simple description and a recipe that reproduces the bug.  Try to
create a minimal document that demonstrates the bug.  The easier you
make it to understand and track down the bug, the more likely a fix
will be.

Now you're ready to write the bug report.  Please include:

* A clear description of the bug.  Describe how you expected Docutils
  to behave, and contrast that with how it actually behaved.  While
  the bug may seem obvious to you, it may not be so obvious to someone
  else, so it's best to avoid a guessing game.

* A complete description of the environment in which you reproduced
  the bug:

  - Your operating system & version.
  - The version of Python (``python -V``).
  - The version of Docutils (use the "-V" option to most Docutils
    front-end tools).
  - Any private modifications you made to Docutils.
  - Anything else that could possibly be relevant.  Err on the side
    of too much information, rather than too little.

* A literal transcript of the *exact* command you ran, and the *exact*
  output.  Use the "--traceback" option to get a complete picture.

* The exact input and output files.  Better to attach complete files
  to your bug report than to include just a summary or excerpt.

* If you also want to include speculation as to the cause, and even a
  patch to fix the bug, that would be great!

The best place to send your bug report is to the `SourceForge Bug
Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
open bug report on SourceForge is a constant irritant that begs to be
squashed.

Thank you!

(This section was inspired by the `Subversion project's`__ BUGS__
file.)

.. [1] Due to overwhelming amounts of spam, the
   docutils-users@lists.sourceforge.net mailing list has been set up
   for subscriber posting only.  Non-subscribers who post to
   docutils-users will receive a message with "Subject: Your message
   to Docutils-users awaits moderator approval".  Legitimate messages
   are accepted and posted as soon as possible (a list administrator
   must verify the message manually).  If you'd like to subscribe to
   docutils-users, please visit
   <http://lists.sourceforge.net/lists/listinfo/docutils-users>.

__ http://subversion.tigris.org/
__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup

.. _CVS: http://sourceforge.net/cvs/?group_id=38414
.. _development snapshot: http://docutils.sf.net/#development-snapshot
.. _documentation: docs/
.. _FAQ: FAQ.html
.. _mailing list archives: http://docutils.sf.net/#mailing-lists
.. _SourceForge Bug Tracker:
   http://sourceforge.net/tracker/?group_id=38414&atid=422030


Known Bugs
==========

Also see the `SourceForge Bug Tracker`_.

* ``utils.relative_path()`` sometimes returns absolute _`paths on
  Windows` (like ``C:/test/foo.css``) where it could have chosen a
  relative path.

  Furthermore, absolute pathnames are inserted verbatim, like
  ``href="C:/test/foo.css"`` instead of
  ``href="file:///C:/test/foo.css"``.

  For details, see `this posting by Alan G. Isaac
  <http://article.gmane.org/gmane.text.docutils.user/1569>`_.

* _`Line numbers` in system messages are inconsistent in the parser.

  - In text inserted by the "include" directive, errors are often not
    reported with the correct "source" or "line" numbers.  Perhaps all
    Reporter calls need "source" and "line" keyword arguments.
    Elements' .line assignments should be checked.  (Assign to .source
    too?  Add a set_info method?  To what?)  There's a test in
    test/test_parsers/test_rst/test_directives/test_include.py.

  - Some line numbers in elements are not being set properly
    (explicitly), just implicitly/automatically.  See rev. 1.74 of
    docutils/parsers/rst/states.py for an example of how to set.

* .. _none source:

  Quite a few nodes are getting a "None" source attribute as well.  In
  particular, see the bodies of definition lists.

* David Abrahams pointed out that _`doubly-indirect substitutions`
  have a bug, but only when there's multiple references::

      |substitute| my coke for gin
      |substitute| you for my mum
      at least I'll get my washing done

      .. |substitute| replace:: |replace|
      .. |replace| replace:: swap

  This is tricky.  Substitutions have to propagate back completely.

* .. _substitutions and references:

  Another bug from David Abrahams (run with ``rst2html.py --traceback``)::

      |substitution| and again a |substitution|.

      .. |substitution| replace:: ref__

      __ a.html
      __ b.html

  Change the references.Substitutions tranform's priority from 220 to
  680, so it happens after reference resolution?  Then we have to deal
  with multiple IDs.  Perhaps the Substitution transform should remove
  all IDs from definitions after the first substitution reference is
  processed.

* Footnote label "5" should be "4"::

      $ rst2pseudoxml.py <<EOF
      > ref [#abc]_ [#]_ [1]_ [#4]_
      > 
      > .. [#abc] footnote
      > .. [#] two
      > .. [1] one
      > .. [#4] four
      > EOF
      <document source="<stdin>">
          <paragraph>
              ref
              <footnote_reference auto="1" ids="id1" refid="abc">
                  2

              <footnote_reference auto="1" ids="id2" refid="id5">
                  3

              <footnote_reference ids="id3" refid="id6">
                  1

              <footnote_reference auto="1" ids="id4" refid="id7">
                  5
          <footnote auto="1" backrefs="id1" ids="abc" names="abc">
              <label>
                  2
              <paragraph>
                  footnote
          <footnote auto="1" backrefs="id2" ids="id5" names="3">
              <label>
                  3
              <paragraph>
                  two
          <footnote backrefs="id3" ids="id6" names="1">
              <label>
                  1
              <paragraph>
                  one
          <footnote auto="1" backrefs="id4" ids="id7" names="4">
              <label>
                  5
              <paragraph>
                  four

\f
..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: