LaTeX writer: New algorithm for table colum widths. Fixes bug #422.

New configuration setting "legacy_column_widths" for backwards
compatibility.

Only write "continued on next page..." if it fits without
making the table columns wider.

Table `width` option overrides conflicting "auto" column `widths`.

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

1 files changed, 62 insertions, 55 deletions

diff --git a/docutils/test/functional/input/data/tables_latex.txt b/docutils/test/functional/input/data/tables_latex.txt
index 4b48bd296..7bd55b478 100644
--- a/docutils/test/functional/input/data/tables_latex.txt
+++ b/docutils/test/functional/input/data/tables_latex.txt
@@ -4,8 +4,6 @@ Tables
 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
@@ -20,14 +18,11 @@ specifying column widths computed from the source:
    | 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. [#]_
+To provide for arbitrary cell content, the LaTeX writer defaults to
+specifying column widths computed from the source column widths. This
+works sufficiently in many cases:
 
-.. table:: a table with multi-paragraph multicolumn cells
+.. table:: a table with multi-paragraph multi-column cells
 
   +----------+--------------+---------------------------------+-----------+
   | test     | **bold hd**  | multicolumn 1                   | *emph hd* |
@@ -45,17 +40,9 @@ The algorightm provides a working solution in many cases. [#]_
   | 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. [#]_
+A problem with the source-derived column widths is that simple tables
+often use no padding while grid tables without padding look cramped:
 
 .. table:: simple table, not padded in the source
 
@@ -76,6 +63,8 @@ whenever possible is recommended. [#]_
    | EUR | b | c | d |
    +-----+---+---+---+
 
+For better typographic results, setting the `width` and/or
+`widths` options of the `table directive`_ is recommended.
 
 .. table:: grid table, auto-width columns
    :widths: auto
@@ -88,17 +77,23 @@ whenever possible is recommended. [#]_
    | EUR | b | c | d |
    +-----+---+---+---+
 
+.. table:: table with multi-row header and "auto" column-widths
+   :widths: auto
 
-.. [#] 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.
+   +------------+-------------------+
+   | XXX        | Variable Summary  |
+   |            +-------------------+
+   |            | Description       |
+   +============+===================+
+   | multi-column cell              |
+   +--------------------------------+
 
-If a specific total width is desired, "auto" column widths fail,
+The `width` option overrides "auto" `widths` as standard LaTeX tables
+don't have a global width setting:
 
-.. table:: 75% wide table with "auto" column widths
+.. table:: This table has `widths` "auto" (ignored) and `width` 60%.
    :widths: auto
-   :width: 75%
+   :width: 60%
 
    === = = =
     A  B C D
@@ -107,41 +102,53 @@ If a specific total width is desired, "auto" column widths fail,
    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
-   === = = =
+.. _table directive:
+   https://docutils.sourceforge.io/docs/ref/rst/directives.html#table
 
-.. [#] Bug: The table "width" option is currently ignored.
 
-.. table:: table with multirow header and "auto" column-widths
-   :widths: auto
+Nested tables
+-------------
+
++-----------------------------------------+-----------------+
+| Lorem ipsum dolor sit amet, consectetur | adipisicing elit|
++-----------------------------------------+-----------------+
+| .. table::                              | cell 1, 2       |
+|     :align: right                       |                 |
+|                                         |                 |
+|     +-----+-----+                       |                 |
+|     |  1  |  2  |                       |                 |
+|     +-----+-----+                       |                 |
++-----------------------------------------+-----------------+
+| table width depends on parent column    | same table      |
+|                                         |                 |
+| .. table::                              |                 |
+|     :align: center                      |                 |
+|                                         |                 |
+|     +-----+-----+                       | +-----+-----+   |
+|     |  1  |  2  |                       | |  1  |  2  |   |
+|     +-----+-----+                       | +-----+-----+   |
+|                                         |                 |
+| better use "auto" widths, see below     | in narrow column|
++-----------------------------------------+-----------------+
+| .. table::                              | cell 3, 2       |
+|     :align: right                       |                 |
+|     :widths: auto                       |                 |
+|                                         |                 |
+|     +-----+-----+                       |                 |
+|     |  1  |  2  |                       |                 |
+|     +-----+-----+                       |                 |
+|                                         |                 |
+| definition:                             |                 |
+|             list                        |                 |
++-----------------------------------------+-----------------+
 
-   +------------+-------------------+
-   | XXX        | Variable Summary  |
-   |            +-------------------+
-   |            | Description       |
-   +============+===================+
-   | multicollumn cell              |
-   +--------------------------------+
 
 TODO
 ----
 
-Limit the total width of a table to the ``\linewidth``, unless the table
-width is explicitely specified in the source.
+* Tables with multi-paragraph multi-row cells currently fail due to a
+  LaTeX limitation (see https://sourceforge.net/p/docutils/bugs/225/).
 
-Tables with multi-paragraph multirow cells currently fail due to a LaTeX
-limitation (see https://sourceforge.net/p/docutils/bugs/225/).
+* Tweak vertical spacing in table cells containing multiple elements.
 
-
-.. _table directive:
-   https://docutils.sourceforge.io/docs/ref/rst/directives.html#table
+See also ``test/functional/input/data/latex-problematic.txt``.