Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
================
Docutils_ Bugs
================
:Author: David Goodger; open to all Docutils developers
:Contact: [email protected]
:Date: $Date: 2010-10-11 14:32:33 +0200 (Mon, 11 Okt 2010) $
:Revision: $Revision: 6443 $
: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
the repository_ or from the current 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_ 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 example`_ that demonstrates the bug. The easier you
make it to understand and track down the bug, the more likely a fix
will be.
.. sidebar:: minimal example
.. _minimal example:
A minimal example is an example which is as small as possible. These
examples are much easier to understand than long examples.
To construct an example which is as small as possible, the rule is
quite simple: *remove anything which is not necessary*.
See also: `LaTeX FAQ`__, `Lilypond Documentation`__, minimalbeispiel.de__
__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
__ http://lilypond.org/doc/v2.9/Documentation/user/lilypond/Minimal-examples
__ http://www.minimalbeispiel.de/mini-en.html
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. Create a `minimal example`_
of the failing behaviour — it is 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.)
__ http://subversion.tigris.org/
__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
.. _CVS: http://sourceforge.net/cvs/?group_id=38414
.. _repository: docs/dev/repository.html
.. _snapshot: http://docutils.sourceforge.net/#download
.. _documentation: docs/
.. _FAQ: FAQ.html
.. _mailing list archives: http://docutils.sf.net/#mailing-lists
.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
.. _SourceForge Bug Tracker:
http://sourceforge.net/tracker/?group_id=38414&atid=422030
Known Bugs
==========
Also see the `SourceForge Bug Tracker`_.
* .. _error reporting:
Calling rst2s5.py with a non-existent theme (``--theme
does_not_exist``)
causes exceptions. Such errors should be handled more gracefully.
* The "stylesheet" setting (a URL, to be used verbatim) should be
allowed to be combined with "embed_stylesheet". The stylesheet data
should be read in using urllib. There was an assumption that a
stylesheet to be embedded should exist as a file on the local
system, and only the "stylesheet_path" setting should be used.
* ``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
`_.
* Footnote label "5" should be "4" when processing the following
input::
ref [#abc]_ [#]_ [1]_ [#4]_
.. [#abc] footnote
.. [#] two
.. [1] one
.. [#4] four
Output::
ref
2
3
1
5
