#504 errors for malformed tables do not indicate what the error is

[Jynn Nelson]

The error messages for malformed tables are quite long and do not indicate where the error occurred. I expect docutils to point at a single line of code, and say why it was malformed. Instead it points at the whole table and just says "malformed table".

$ grep PRETTY /etc/os-release
PRETTY_NAME="Pop!_OS 22.04 LTS"
$ python -V
Python 3.10.12
$ docutils -V
docutils (Docutils 0.21.2, Python 3.10.12, on linux)
$ docutils --traceback table.rst >/dev/null
table.rst:5: (ERROR/3) Malformed table.

+-------------------------+-------------------+
| Standard Code           | Message(s)       |
+=========================+===================+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M2, Invalid combination | None              |
+-------------------------+-------------------+

Note that docutils does have the information to report this bug, because I can see it in a debugger. It simply doesn't include that info in the error.

$ python -m pdb $(which docutils) --traceback table.rst
> /home/jyn/.local/bin/docutils(3)<module>()
-> import re
(Pdb) break docutils/parsers/rst/states.py:1787
Breakpoint 1 at /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py:1787
(Pdb) c
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1787)malformed_table()
-> message = 'Malformed table.'
(Pdb) up
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1737)isolate_grid_table()
-> messages.extend(self.malformed_table(block))
(Pdb) list
1732                else:
1733                    messages.extend(self.malformed_table(block))
1734                    return [], messages, blank_finish
1735            for i in range(len(block)):     # check right edge
1736                if len(block[i]) != width or block[i][-1] not in '+|':
1737 ->                 messages.extend(self.malformed_table(block))
1738                    return [], messages, blank_finish
1739            return block, messages, blank_finish
1740    
1741        def isolate_simple_table(self):
1742            start = self.state_machine.line_offset
(Pdb) p block[i]
'| Standard Code           | Message(s)       |'
(Pdb) p width
47
(Pdb) p len(block[i])
46

[Günter Milde]

Thank you for the report.

Note, that Docutils does report the line in the table for "simple" tables:

========================   =================
 Standard Code             Message(s)       
========================   =================
 M1, indicator undefined  Illegal reference
 M2, Invalid combination   None             
========================   =================

Compiling with docutils reports

/tmp/foo.rst:4: (ERROR/3) Malformed table.
Text in column margin in table line 4.
...

[Günter Milde]

A fix is in [patches:#214] by OP Jynn Nelson . Thanks.