Update functional test for LaTeX corner cases.

Test for more problems with tables.

Cosmetic fixes, reword, restructure.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8810 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

5 files changed, 185 insertions, 251 deletions

diff --git a/docutils/test/functional/input/data/latex_encoding.txt b/docutils/test/functional/input/data/latex_encoding.txt
index 2544757fa..a18ce023a 100644
--- a/docutils/test/functional/input/data/latex_encoding.txt
+++ b/docutils/test/functional/input/data/latex_encoding.txt
@@ -1,7 +1,7 @@
-Encoding special chars
-======================
+Encoding special characters
+===========================
 
-The LaTeX Info pages lists under "2.18 Special Characters"
+The LaTeX Info pages list under "2.18 Special Characters"
 
   The following characters play a special role in LaTeX and are called
   "special printing characters", or simply "special characters".
diff --git a/docutils/test/functional/input/data/tables_latex.txt b/docutils/test/functional/input/data/tables_latex.txt
index beecf6b21..4b48bd296 100644
--- a/docutils/test/functional/input/data/tables_latex.txt
+++ b/docutils/test/functional/input/data/tables_latex.txt
@@ -1,30 +1,128 @@
-More Tables
-===========
-
-A table with multi-paragraph multicolumn cells:
-
-+----------+--------------+---------------------------------+-----------+
-| test     | **bold hd**  | multicolumn 1                   | *emph hd* |
-|          |              |                                 |           |
-|          |              | With a second paragraph         |           |
-+----------+--------------+--------------+--------+---------+-----------+
-| multicolumn 2           | cell         | cell   | cell    | cell      |
-|                         |              |        |         |           |
-| With a second paragraph |              |        |         |           |
-+----------+--------------+--------------+--------+---------+-----------+
-| cell     | multicolumn 3 (one line,    | cell   | cell    | cell      |
-|          | but very very very very     |        |         |           |
-|          | very looooong)              |        |         |           |
-+----------+--------------+--------------+--------+---------+-----------+
-| cell     | cell         | cell         | Short multicolumn 4          |
-+----------+--------------+--------------+------------------------------+
+Tables
+======
 
-Tables with multi-paragraph multirow cells currently fail due to a LaTeX
-limitation (see https://sourceforge.net/p/docutils/bugs/225/).
+In contrast to HTML, LaTeX does not support line-breaks in tables with
+"automatic" column widths. Each cell has just one line, paragraphs are
+merged (the writer emits a warning).
+To provide for arbitrary cell content, the LaTeX writer defaults to
+specifying column widths computed from the source:
+
+.. table:: problems with "auto" widths
+   :widths: auto
+
+   +-----------+------------------+
+   | 11        | first paragraph  |
+   |           |                  |
+   |           | second paragraph |
+   +-----------+------------------+
+   | content   | 22               |
+   | with      |                  |
+   | linebreak |                  |
+   +-----------+------------------+
+
+Docutils stores table column widths in the "doctree" (in characters,
+excluding the separator). In the .tex source, column widths are written
+as percent of the ``\linewidth``, computed on the assumption that an
+average text line is 80 characters wide. An allowance added to the stored
+column widths compensates the padding (``\tabcolsep``) added by LaTeX.
+The algorightm provides a working solution in many cases. [#]_
+
+.. table:: a table with multi-paragraph multicolumn cells
+
+  +----------+--------------+---------------------------------+-----------+
+  | test     | **bold hd**  | multicolumn 1                   | *emph hd* |
+  |          |              |                                 |           |
+  |          |              | With a second paragraph         |           |
+  +----------+--------------+--------------+--------+---------+-----------+
+  | multicolumn 2           | cell         | cell   | cell    | cell      |
+  |                         |              |        |         |           |
+  | With a second paragraph |              |        |         |           |
+  +----------+--------------+--------------+--------+---------+-----------+
+  | cell     | multicolumn 3 (one line,    | cell   | cell    | cell      |
+  |          | but very very very very     |        |         |           |
+  |          | very looooong)              |        |         |           |
+  +----------+--------------+--------------+--------+---------+-----------+
+  | cell     | cell         | cell         | Short multicolumn 4          |
+  +----------+--------------+--------------+------------------------------+
+
+.. [#] Currently, computed column widths are too wide.
+   TODO: Account for the ``\tabcolsep``.
+
+For good typographic results experimenting with the "width" and "widths"
+options of the `table directive`_ may be required. (Unfortunately, the
+interpretation of these values differs between LaTeX writer and HTML
+writer.)
+
+Simple tables use often no padding in the source while grid tables
+without padding look clumsy. Setting ``:widths: auto`` in the source
+whenever possible is recommended. [#]_
+
+.. table:: simple table, not padded in the source
+
+   === = = =
+    A  B C D
+   === = = =
+   100 2 3 4
+   EUR b c d
+   === = = =
+
+.. table:: grid table, padded cells
+
+   +-----+---+---+---+
+   |  A  | B | C | D |
+   +=====+===+===+===+
+   | 100 | 2 | 3 | 4 |
+   +-----+---+---+---+
+   | EUR | b | c | d |
+   +-----+---+---+---+
+
+
+.. table:: grid table, auto-width columns
+   :widths: auto
 
-A table with multirow header and column-widths set by LaTeX:
+   +-----+---+---+---+
+   |  A  | B | C | D |
+   +=====+===+===+===+
+   | 100 | 2 | 3 | 4 |
+   +-----+---+---+---+
+   | EUR | b | c | d |
+   +-----+---+---+---+
 
-.. table::
+
+.. [#] Currently, the last column is extra wide because the
+   writer adds a hint "... continued on next page" to longtables with a
+   header row. The hint is only shown if the table does not fit on one
+   page but always affects the table width.
+
+If a specific total width is desired, "auto" column widths fail,
+
+.. table:: 75% wide table with "auto" column widths
+   :widths: auto
+   :width: 75%
+
+   === = = =
+    A  B C D
+   === = = =
+   100 2 3 4
+   EUR b c d
+   === = = =
+
+but "grid" based or explicit column widths should work: [#]_
+
+.. table:: 75% wide table with explicit column widths
+   :width: 75%
+   :widths: 3 2 2 2
+
+   === = = =
+    A  B C D
+   === = = =
+   100 2 3 4
+   EUR b c d
+   === = = =
+
+.. [#] Bug: The table "width" option is currently ignored.
+
+.. table:: table with multirow header and "auto" column-widths
    :widths: auto
 
    +------------+-------------------+
@@ -35,18 +133,15 @@ A table with multirow header and column-widths set by LaTeX:
    | multicollumn cell              |
    +--------------------------------+
 
-In a table with column-widths set by LaTeX, each cell has just one line.
-Paragraphs are merged (a warning is given).
+TODO
+----
 
-.. table::
-   :widths: auto
+Limit the total width of a table to the ``\linewidth``, unless the table
+width is explicitely specified in the source.
 
-   +------------+-------------------+
-   | 11         | first paragraph   |
-   |            |                   |
-   |            | second paragraph  |
-   |            |                   |
-   |            | third paragraph   |
-   +------------+-------------------+
-   | 21         | 22                |
-   +------------+-------------------+
+Tables with multi-paragraph multirow cells currently fail due to a LaTeX
+limitation (see https://sourceforge.net/p/docutils/bugs/225/).
+
+
+.. _table directive:
+   https://docutils.sourceforge.io/docs/ref/rst/directives.html#table
diff --git a/docutils/test/functional/input/data/unicode.txt b/docutils/test/functional/input/data/unicode.txt
index 90dfbce7a..796793a12 100644
--- a/docutils/test/functional/input/data/unicode.txt
+++ b/docutils/test/functional/input/data/unicode.txt
@@ -1,45 +1,46 @@
 Non-ASCII characters
 ====================
 
-Punctuation and footnote symbols
-
-= ===================================
-– en-dash
-— em-dash
-‘ single turned comma quotation mark
-’ single comma quotation mark
-‚ low single comma quotation mark
-“ double turned comma quotation mark
-” double comma quotation mark
-„ low double comma quotation mark
-† dagger
-‡ double dagger
-♦ black diamond suit
-♥ black heart suit
-♠ black spade suit
-♣ black club suit
-… ellipsis
-™ trade mark sign
-⇔ left-right double arrow
-= ===================================
-
-
-The `Latin-1 extended` Unicode block
-
-===  =  =  =  =  =  =  =  =  =  =
- ..  0  1  2  3  4  5  6  7  8  9
----  -  -  -  -  -  -  -  -  -  -
-160     ¡  ¢  £     ¥  ¦  §  ¨  ©
-170  ª  «  ¬  ­  ®  ¯  °  ±  ²  ³
-180  ´  µ  ¶  ·  ¸  ¹  º  »  ¼  ½
-190  ¾  ¿  À  Á  Â  Ã  Ä  Å  Æ  Ç
-200  È  É  Ê  Ë  Ì  Í  Î  Ï  Ð  Ñ
-210  Ò  Ó  Ô  Õ  Ö  ×  Ø  Ù  Ú  Û
-220  Ü  Ý  Þ  ß  à  á  â  ã  ä  å
-230  æ  ç  è  é  ê  ë  ì  í  î  ï
-240  ð  ñ  ò  ó  ô  õ  ö  ÷  ø  ù
-250  ú  û  ü  ý  þ  ÿ
-===  =  =  =  =  =  =  =  =  =  =
+.. table:: Punctuation and footnote symbols
+   :widths: auto
+
+   = ===================================
+   – en-dash
+   — em-dash
+   ‘ single turned comma quotation mark
+   ’ single comma quotation mark
+   ‚ low single comma quotation mark
+   “ double turned comma quotation mark
+   ” double comma quotation mark
+   „ low double comma quotation mark
+   † dagger
+   ‡ double dagger
+   ♦ black diamond suit
+   ♥ black heart suit
+   ♠ black spade suit
+   ♣ black club suit
+   … ellipsis
+   ™ trade mark sign
+   ⇔ left-right double arrow
+   = ===================================
+
+.. table:: The `Latin-1 extended` Unicode block
+   :widths: auto
+
+   ===  =  =  =  =  =  =  =  =  =  =
+    ..  0  1  2  3  4  5  6  7  8  9
+   ---  -  -  -  -  -  -  -  -  -  -
+   160     ¡  ¢  £     ¥  ¦  §  ¨  ©
+   170  ª  «  ¬  ­  ®  ¯  °  ±  ²  ³
+   180  ´  µ  ¶  ·  ¸  ¹  º  »  ¼  ½
+   190  ¾  ¿  À  Á  Â  Ã  Ä  Å  Æ  Ç
+   200  È  É  Ê  Ë  Ì  Í  Î  Ï  Ð  Ñ
+   210  Ò  Ó  Ô  Õ  Ö  ×  Ø  Ù  Ú  Û
+   220  Ü  Ý  Þ  ß  à  á  â  ã  ä  å
+   230  æ  ç  è  é  ê  ë  ì  í  î  ï
+   240  ð  ñ  ò  ó  ô  õ  ö  ÷  ø  ù
+   250  ú  û  ü  ý  þ  ÿ
+   ===  =  =  =  =  =  =  =  =  =  =
 
 * The following line should not be wrapped, because it uses
   no-break spaces (\\u00a0):
diff --git a/docutils/test/functional/input/data/urls.txt b/docutils/test/functional/input/data/urls.txt
index a3c8a9129..2f81ab1c6 100644
--- a/docutils/test/functional/input/data/urls.txt
+++ b/docutils/test/functional/input/data/urls.txt
@@ -45,7 +45,7 @@ __ A:DOS\\path\\
 
 
 * ``^^`` LaTeX's special syntax for characters results in "strange" replacements
-  (both with ``\href`` and ``\url``). A warning is given.
+  (both with ``\href`` and ``\url``). The writer emits a warning.
 
   `file with ^^ <../strange^^name>`__:
   `<../strange^^name>`__
diff --git a/docutils/test/functional/input/latex_cornercases.txt b/docutils/test/functional/input/latex_cornercases.txt
index fa37bdb03..f4c756d5b 100644
--- a/docutils/test/functional/input/latex_cornercases.txt
+++ b/docutils/test/functional/input/latex_cornercases.txt
@@ -1,18 +1,13 @@
 Additional Tests for the LaTeX Writer
-=====================================
+*************************************
 
 These tests contain syntax elements and combinations which may cause
 trouble for the LaTeX writer.
 
+.. contents::
+
 .. include:: data/section_titles.txt
-.. include:: data/tables_latex.txt
 .. include:: data/option_lists.txt
-.. include:: data/nonalphanumeric.txt
-.. include:: data/unicode.txt
-.. include:: data/latex_encoding.txt
-.. include:: data/hyperlinking.txt
-.. include:: data/urls.txt
-
 
 Block Quotes
 ============
@@ -58,166 +53,9 @@ Image with 100% width:
 .. image:: ../../../docs/user/rst/images/title.png
    :width: 100%
 
-
-Rowspanning tables
-==================
-
-Several rowspanning cells in a table.
-
-Problem:
-
-In LaTeX, "overwritten" cells need to be defined as empty cells.
-
-Docutils (similarily to HTML) uses is the "Exchange Table Model" (also known
-as CALS tables, see docs/ref/soextblx.dtd) which defines only the remaining
-cells in a row "affected" by multirow cells.
-
-Therefore, visit_entry() is only called for the remaining cells and the
-LaTeX writer needs bookkeeping to write out the required number of extra
-'&'s.
-
-+-----+----------+----------+------+
-| 11  |       12 |       13 |  14  |
-+-----+----------+----------+------+
-| 21  | 2/3 2    |          |  24  |
-+-----+          |          +------+
-| 31  |          | 2…4 3    |  34  |
-+-----+----------+          +------+
-| 41  |       42 |          |  14  |
-+-----+----------+----------+------+
-
-+-------+-------+----+
-| 11    |    12 | 13 |
-+-------+-------+----+
-| 2/3 1 |       | 23 |
-|       |       +----+
-|       | 2/3 2 | 33 |
-+-------+-------+----+
-
-+-------+----+
-| 11    | 12 |
-+-------+----+
-| 2/3 1 | 22 |
-|       +----+
-|       | 32 |
-+-------+----+
-
-+----+--------+----+
-| 11 |    12  | 13 |
-+----+--------+----+
-| 21 | 2/3 2  | 23 |
-+----+        +----+
-| 31 |        | 33 |
-+----+--------+----+
-
-+----+--------+
-| 11 | 12     |
-+----+--------+
-| 21 | 2/3 1  |
-+----+        |
-| 31 |        |
-+----+--------+
-
-
-+----+--------+
-| 11 | 1/2 1  |
-+----+        |
-| 21 |        |
-+----+--------+
-| 31 | 32     |
-+----+--------+
-
-+----+------------+--------+
-| 11 | 1/2 2      |        |
-+----+            | 1/2 3  |
-| 21 |            |        |
-+----+------------+--------+
-
-+-------+----+--------+
-|       | 12 | 1/2 3  |
-| 1/2 3 +----+        |
-|       | 22 |        |
-+-------+----+--------+
-
-+-------+----+
-|       | 12 |
-| 1/2 3 +----+
-|       | 22 |
-+-------+----+
-| 31    | 32 |
-+-------+----+
-
-Nested tables
-=============
-
-TODO:
-Set alignment of nested tables without creating too much vertical space.
-
-+-----------------------------------------+-----------------+
-| Lorem ipsum dolor sit amet, consectetur | adipisicing elit|
-+-----------------------------------------+-----------------+
-| .. table::                              | cell 1, 2       |
-|                                         |                 |
-|     +-----+-----+                       |                 |
-|     |  1  |  2  |                       |                 |
-|     +-----+-----+                       |                 |
-+-----------------------------------------+-----------------+
-| .. table::                              | cell 1, 2       |
-|     :align: left                        |                 |
-|                                         |                 |
-|     +-----+-----+                       |                 |
-|     |  1  |  2  |                       |                 |
-|     +-----+-----+                       |                 |
-+-----------------------------------------+-----------------+
-| .. table::                              | cell 1, 2       |
-|     :align: center                      |                 |
-|                                         |                 |
-|     +-----+-----+                       |                 |
-|     |  1  |  2  |                       |                 |
-|     +-----+-----+                       |                 |
-+-----------------------------------------+-----------------+
-| .. table::                              | cell 1, 2       |
-|     :align: right                       |                 |
-|                                         |                 |
-|     +-----+-----+                       |                 |
-|     |  1  |  2  |                       |                 |
-|     +-----+-----+                       |                 |
-+-----------------------------------------+-----------------+
-| .. table::                              | cell 2, 2       |
-|     :align: right                       |                 |
-|                                         |                 |
-|     +-----+-----+                       |                 |
-|     |  1  |  2  |                       |                 |
-|     +-----+-----+                       |                 |
-|                                         |                 |
-| definition:                             |                 |
-|             list                        |                 |
-+-----------------------------------------+-----------------+
-|                                         |       cell 3, 2 |
-+-----------------------------------------+-----------------+
-
-.. table::
-  :class: booktabs
-
-  +-----------------------------------------+-----------------+
-  | Lorem ipsum dolor sit amet, consectetur | adipisicing elit|
-  +-----------------------------------------+-----------------+
-  | .. table::                              | cell 1, 2       |
-  |     :align: right                       |                 |
-  |                                         |                 |
-  |     +-----+-----+                       |                 |
-  |     |  1  |  2  |                       |                 |
-  |     +-----+-----+                       |                 |
-  +-----------------------------------------+-----------------+
-  | .. table::                              | cell 2, 2       |
-  |     :align: right                       |                 |
-  |                                         |                 |
-  |     +-----+-----+                       |                 |
-  |     |  1  |  2  |                       |                 |
-  |     +-----+-----+                       |                 |
-  |                                         |                 |
-  | definition:                             |                 |
-  |             list                        |                 |
-  +-----------------------------------------+-----------------+
-  |                                         |       cell 3, 2 |
-  +-----------------------------------------+-----------------+
+.. include:: data/tables_latex.txt
+.. include:: data/nonalphanumeric.txt
+.. include:: data/unicode.txt
+.. include:: data/latex_encoding.txt
+.. include:: data/hyperlinking.txt
+.. include:: data/urls.txt