Thread: [Docstring-develop] Bug or misfeature? Negative integers in tables
Status: Pre-Alpha
Brought to you by:
goodger
Menu
▾
▴
docstring-develop
|
From: Ueli S. <u_s...@bl...> - 2002-04-16 21:56:18
|
David,
After lots of painless usage, I had my first unpleasant surprise with
reStructuredText recently, when negative integers in tables appeared
in monospaced text in my browser. It wasn't very hard to find out why
-- they are recognised as option lists items and have empty
descriptions. An `example file`_ is attached below.
If my interpretation of the DTD is correct, then this behaviour is a
bug. From my limited understanding of XML, ``description`` entities
contain ``body.elements``, and these in turn can't be empty -- please
correct my if I'm wrong on this!
Otherwise, it's probably a misfeature. Negative integers as table
elements are probably a frequent case in daily life (especially since
reST is intended for more than "just" Python docstrings!), and the
surprise I had should be avoided. I see three ways around it:
- Require non-empty descriptions for options (so a negative integer by
itself surrounded by blank lines would be a paragraph, or an error
within an option list);
- Disallow option lists in tables (and maybe other constructs too?);
- Documenting this behaviour.
The second point compromises the ability to document reST with itself,
so -1 on this one. The third one isn't really a solution for obvious
reasons, so -2 ... The first solution probably doesn't break
anything, so it's my preferred one.
What do you think?
Ueli
.. _`example file`:
----------------------------------------------------------------------
The table:
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|-1000 |Negative integers are options... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|-200 |This option list consists of two options |
|-300 |and an option group. |
|-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
was entered as::
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|-1000 |Negative integers are options... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|-200 |This option list consists of two options |
|-300 |and an option group. |
|-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
but should, IMHO, be rendered as:
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|\-1000 |Negative integers need quoting... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|\-200 |A bunch of negative numbers. |
|\-300 | |
|\-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
without the need for quoting the negative integer. This time, I
entered the table as::
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|\-1000 |Negative integers need quoting... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|\-200 |A bunch of negative numbers. |
|\-300 | |
|\-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
.. Note::
Incidentally, I once meant to enter an option list, but typed::
-1 Option "1"
-2
- 4 Option "4". Option "2" proves that options need no
description.
first. I found the warning ::
Reporter: WARNING (2) Unindent without blank line at line <deleted>.
not very helpful...
|
|
From: David G. <go...@us...> - 2002-04-16 22:55:29
|
Hi Ueli,
You've definitely found a bug. The negative numbers are the key here; the
tables have nothing to do with it. A freestanding paragraph like this would
also produce incorrect output:
-1
I think your first suggestion is the way to go:
> Require non-empty descriptions for options
I'll try to fix it as soon as possible.
If you find any other surprises, an easy way to diagnose them is to use the
"publish.py" front-end, which produces pretty-printed pseudo-XML of the
internal data strucutre. It will show you exactly what the parser sees.
Thanks for the bug report!
--
David Goodger go...@us... Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net
|
|
From: David G. <go...@us...> - 2002-04-18 03:03:04
|
The bug with negative numbers being mistaken for option lists has been fixed in CVS. CVS snapshots are also available. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
|
From: David G. <go...@us...> - 2002-04-21 03:33:07
|
Ueli wrote:
> Incidentally, I once meant to enter an option list, but typed::
>
> -1 Option "1"
> -2
> - 4 Option "4". Option "2" proves that options need no
> description.
>
> first. I found the warning ::
>
> Reporter: WARNING (2) Unindent without blank line at line <deleted>.
>
> not very helpful...
I've improved the system messages. The parser now reports:
Reporter: WARNING (2) Option list ends without a blank line;
unexpected unindent at line 2.
Other cases of a construct ending without a blank line (which is often
because of a markup problem) now offer similarly improved diagnostics. If
you find any other, please let me know!
--
David Goodger <go...@us...> Open-source projects:
- Python Docutils: http://docutils.sourceforge.net/
- The Go Tools Project: http://gotools.sourceforge.net/
|
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X