[Docstring-develop] Bug or misfeature? Negative integers in tables
Status: Pre-Alpha
Brought to you by:
goodger
Menu
▾
▴
[Docstring-develop] Bug or misfeature? Negative integers in tables
|
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...
|
