| Server IP : 127.0.0.2 / Your IP : 13.59.234.246 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/python-docutils/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Docutils Bugs</title>
<meta name="author" content="David Goodger; open to all Docutils developers" />
<meta name="date" content="2013-06-06" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-bugs">
<h1 class="title"><a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> Bugs</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger; open to all Docutils developers</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:goodger@python.org">goodger@python.org</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2013-06-06</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7670</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<p>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.</p>
<p>This document describes how to report a bug, and lists known bugs.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#how-to-report-a-bug" id="id5">How To Report A Bug</a></li>
<li><a class="reference internal" href="#known-bugs" id="id6">Known Bugs</a></li>
</ul>
</div>
<div class="section" id="how-to-report-a-bug">
<h1><a class="toc-backref" href="#id5">How To Report A Bug</a></h1>
<p>If you think you've discovered a bug, please read through these
guidelines before reporting it.</p>
<p>First, make sure it's a new bug:</p>
<ul>
<li><p class="first">Please check the list of <a class="reference internal" href="#known-bugs">known bugs</a> below and the <a class="reference external" href="http://sourceforge.net/tracker/?group_id=38414&atid=422030">SourceForge
Bug Tracker</a> to see if it has already been reported.</p>
</li>
<li><p class="first">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 <a class="reference external" href="docs/dev/repository.html">repository</a> or from the current <a class="reference external" href="http://docutils.sourceforge.net/#download">snapshot</a> 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.</p>
<p>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.</p>
</li>
<li><p class="first">If Docutils does not behave the way you expect, look in the
<a class="reference external" href="docs/">documentation</a> (don't forget the <a class="reference external" href="FAQ.html">FAQ</a>!) and <a class="reference external" href="http://docutils.sf.net/#mailing-lists">mailing list archives</a>
for evidence that it should behave the way you expect.</p>
</li>
</ul>
<p>If you're not sure, please ask on the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing list
first.</p>
<hr class="docutils" />
<p>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 <a class="reference internal" href="#minimal-example">minimal example</a> that demonstrates the bug. The easier you
make it to understand and track down the bug, the more likely a fix
will be.</p>
<div class="sidebar" id="minimal-example">
<p class="first sidebar-title">minimal example</p>
<p>A <cite>minimal working example</cite> is a complete example which is as as small and
simple as possible. It should be complete and working, so that</p>
<ul class="simple">
<li>you cannot accidentally omit information important to diagnosing
the problem and</li>
<li>the person responding can just copy-and-paste the code to try it out.</li>
</ul>
<p>To construct an example which is as small as possible, the rule
quite simple: <em>remove/leave out anything which is not necessary</em>.</p>
<p class="last">See also: <a class="reference external" href="http://www.minimalbeispiel.de/mini-en.html">What is a minimal working example?</a>, <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl">LaTeX FAQ</a></p>
</div>
<p>Now you're ready to write the bug report. Please include:</p>
<ul class="simple">
<li>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.</li>
<li>A complete description of the environment in which you reproduced
the bug:<ul>
<li>Your operating system & version.</li>
<li>The version of Python (<tt class="docutils literal">python <span class="pre">-V</span></tt>).</li>
<li>The version of Docutils (use the "-V" option to most Docutils
front-end tools).</li>
<li>Any private modifications you made to Docutils.</li>
<li>Anything else that could possibly be relevant. Err on the side
of too much information, rather than too little.</li>
</ul>
</li>
<li>A literal transcript of the <em>exact</em> command you ran, and the <em>exact</em>
output. Use the "--traceback" option to get a complete picture.</li>
<li>The exact input and output files. Create a <a class="reference internal" href="#minimal-example">minimal example</a>
of the failing behaviour — it is better to attach complete files
to your bug report than to include just a summary or excerpt.</li>
<li>If you also want to include speculation as to the cause, and even a
patch to fix the bug, that would be great!</li>
</ul>
<p>The best place to send your bug report is to the <a class="reference external" href="http://sourceforge.net/tracker/?group_id=38414&atid=422030">SourceForge Bug
Tracker</a>. 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.</p>
<p>Thank you!</p>
<p>(This section was inspired by the <a class="reference external" href="http://subversion.tigris.org/">Subversion project's</a> <a class="reference external" href="http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup">BUGS</a>
file.)</p>
</div>
<div class="section" id="known-bugs">
<h1><a class="toc-backref" href="#id6">Known Bugs</a></h1>
<p>Also see the <a class="reference external" href="http://sourceforge.net/tracker/?group_id=38414&atid=422030">SourceForge Bug Tracker</a>.</p>
<ul>
<li><p id="error-reporting">Calling rst2s5.py with a non-existent theme (<tt class="docutils literal"><span class="pre">--theme</span>
does_not_exist</tt>)
causes exceptions. Such errors should be handled more gracefully.</p>
</li>
<li><p class="first">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.</p>
</li>
<li><p class="first"><tt class="docutils literal">utils.relative_path()</tt> sometimes returns absolute <span class="target" id="paths-on-windows">paths on
Windows</span> (like <tt class="docutils literal"><span class="pre">C:/test/foo.css</span></tt>) where it could have chosen a
relative path.</p>
<p>Furthermore, absolute pathnames are inserted verbatim, like
<tt class="docutils literal"><span class="pre">href="C:/test/foo.css"</span></tt> instead of
<tt class="docutils literal"><span class="pre">href="file:///C:/test/foo.css"</span></tt>.</p>
<p>For details, see <a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/1569">this posting by Alan G. Isaac</a>.</p>
</li>
<li><p class="first">Footnote label "5" should be "4" when processing the following
input:</p>
<pre class="literal-block">
ref [#abc]_ [#]_ [1]_ [#4]_
.. [#abc] footnote
.. [#] two
.. [1] one
.. [#4] four
</pre>
<p>Output:</p>
<pre class="literal-block">
<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
</pre>
</li>
<li><p class="first">IDs are based on names. Explicit hyperlink targets have priority
over implicit targets. But if an explicit target comes after an
implicit target with the same name, the ID of the first (implicit)
target remains based on the implicit name. Since HTML fragment
identifiers based on the IDs, the first target keeps the name. For
example:</p>
<pre class="literal-block">
.. contents::
Section
=======
.. _contents:
Subsection
----------
text with a reference to contents_ and section_
.. _section:
This paragraph is explicitly targeted with the name "section".
</pre>
<p>When processed to HTML, the 2 internal hyperlinks (to "contents" &
"section") will work fine, but hyperlinks from outside the document
using <tt class="docutils literal"><span class="pre">href="...#contents"</span></tt> and <tt class="docutils literal"><span class="pre">href="...#section"</span></tt> won't work.
Such external links will connect to the implicit targets (table of
contents and "Section" title) instead of the explicit targets
("Subsection" title and last paragraph).</p>
<p>Hyperlink targets with duplicate names should be assigned new IDs
unrelated to the target names (i.e., "id"-prefix serial IDs).</p>
</li>
<li><p class="first">The "contents" ID of the local table of contents in
<tt class="docutils literal">test/functional/expected/standalone_rst_pseudoxml.txt</tt> is lost in
the HTML output at
<tt class="docutils literal">test/functional/expected/standalone_rst_html4css1.html</tt>.</p>
</li>
<li><p class="first"><span class="target" id="blank-first-columns">Blank first columns</span> in simple tables with explicit row separators
silently swallow their input. They should at least produce system
error messages. But, with explicit row separators, the meaning is
unambiguous and ought to be supported:</p>
<pre class="literal-block">
============== ==========
Table with row separators
============== ==========
and blank
-------------- ----------
entries
-------------- ----------
in first
-------------- ----------
columns.
============== ==========
</pre>
<p>Added a commented-out test case to
test/test_parsers/test_rst/test_SimpleTableParser.py.</p>
</li>
<li><p class="first"><span class="target" id="footnote-references-with-hyperlink-targets">Footnote references with hyperlink targets</span> cause a possibly
invalid node tree and make the HTML writer crash:</p>
<pre class="literal-block">
$ rst2pseudoxml.py
[1]_
.. _1: URI
<document source="<stdin>">
<paragraph>
<footnote_reference ids="id1" refuri="URI">
1
<target ids="id2" names="1" refuri="URI">
</pre>
</li>
<li><p class="first">Anonymous references have "name" attributes. Should they? Are they
used? See <tt class="docutils literal">test/test_parsers/test_rst/test_inline_markup.py</tt>.</p>
</li>
<li><p class="first"><reference> elements have a "name" attribute, not "names". The
attribute should be "names"; this is an inconsistency.</p>
</li>
</ul>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</body>
</html>