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