#214 Give better messages on malformed tables

[Jynn Nelson]

This does several things:
- Specifies Misaligned right border for that error, instead of just "malformed table".
- Shows the line where each error happened, not the line where the table starts.
- This had a complication that line numbers appear to be wrong when include directives are present (they include the lines in the source document, instead of being relative to the included document). Just disabled the new smarter logic in that case.
- Changes malformed_table to require both detail and an offset, so poor errors like this can't happen in the future.

Fixes https://sourceforge.net/p/docutils/bugs/504/.

[Günter Milde]

Thank you for the patch. I will have a look at this once 0.22 is out. (We don't want delay the release any further by new changes to the release candidate unless it is urgent.)

[Günter Milde]

I looked at the patch and found a number of issues:

Message "details" misleading if the right border is not misaligned but missing.

System exit with corrupt bottom border:
The compulsory "details" and "offset" arguments for malformed_table() lead to a system exit with traceback - for document authors this is worse than a generic error message. It is also an incompatible change in the Docutils library (some 3rd party extension may use the function...).

     +-----------------------+
     | A table with one cell |
     | & corrupt bottom.     |
     +---------------------- +

The indicated line for simple table with non-matching bottom border is wrong, if the table does not start on line 1 of the document!

If there is no bottom border for a simple table, the complete remaining document may be scanned. Therefore it is both, simpler and more helpful to indicate the start line of a simple table with missing bottom border.

The error "No bottom table border found or no blank line after table bottom." is raised because the markup is ambiguous:

    ==============  ======
    content or      header
    ==============  ======
    this could be   cell content
    or text after   the table

According to the coding policy, lines should be < 80 characters.

The attached patch adresses these points and solves some more issues with the original code.

[Günter Milde]

Fixed in [r10208]. Thank you for report and patch.