SF.net SVN: docutils:[10190 ] trunk/docutils/docs
milde--- via Docutils-checkins <[email protected]> Wed, 30 Jul 2025 08:22:33 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10190
http://sourceforge.net/p/docutils/code/10190
Author: milde
Date: 2025-07-30 08:22:32 +0000 (Wed, 30 Jul 2025)
Log Message:
-----------
Document table width determination by the LaTeX writer.
See also the discussion in the related Sphinx issue
https://github.com/sphinx-doc/sphinx/issues/3411.
Modified Paths:
--------------
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/latex.rst
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-07-29 16:12:15 UTC (rev 10189)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-07-30 08:22:32 UTC (rev 10190)
@@ -892,34 +892,40 @@
The horizontal alignment of the table (new in Docutils 0.13).
``width`` : length_ or percentage_ of the current line width
- Sets the width of the table to the specified length or percentage
- of the line width. If omitted, the renderer determines the width
- of the table based on its contents or the column ``widths``.
+ The width of the table.
+ By default, the renderer determines the width of a table
+ from its contents. [#width-from-widths]_
``widths`` : "auto", "grid", or a `list of integers`_
- Explicitly set column widths.
- Specifies relative widths if used with the ``width`` option.
+ Table column widths.
Possible values:
- .. class:: field-indent-4em run-in
+ .. class:: field-indent-7ex run-in
- :auto: Delegate the determination of column widths to the backend
- (LaTeX, the HTML browser, ...).
+ :"auto": Delegate the determination of column widths to the backend
+ (LaTeX, the HTML browser, ...).
- :grid: Determine column widths from the widths of the input columns
- (in characters).
+ :"grid": Relative column widths match the widths of the columns
+ in the reStructuredText table markup.
- :list of integers: Must match the number of table columns.
- Used instead of the input column widths. Implies *"grid"*.
+ :list of integers: Specifies relative column widths.
+ Must match the number of table columns.
- The default depends on the writer. Most writers default to *grid*. [#]_
+ The default depends on the writer.
+ The HTML5_ and manpage_ writers default to *"auto"*,
+ the html4_ and LaTeX_ writers default to *"grid"*. [#widths-default]_
- .. [#] The `html5 writer`_ defaults to *auto*.
- The default for the HTML and LaTeX writers can be configured
- with the `table_style`_ configuration setting or the special class
- values "colwidths-auto"/"colwidths-grid").
+.. [#width-from-widths] The LaTeX writer determines the `table width
+ from column widths`__ unless the ``widths`` option is set to *"auto"*.
+ __ ../../user/latex.html#table-width
+.. [#widths-default] The ``widths`` default of the HTML and LaTeX
+ writers can be configured with the `table_style`_ configuration
+ setting using the special class values "colwidths-auto" or
+ "colwidths-grid".
+
+
.. _csv-table:
CSV Table
@@ -1032,24 +1038,26 @@
A URI reference to a CSV data file.
``width`` : length_ or percentage_ of the current line width
- Sets the width of the table to the specified length or percentage
- of the line width. If omitted, the renderer determines the width
- of the table based on its contents or the column ``widths``.
+ The width of the table.
+ By default, the renderer determines the width of a table
+ from its contents. [#width-from-widths2]_
``widths`` : `list of integers`_ or "auto"
- A list of relative column widths.
- The default is equal-width columns (100%/#columns).
-
+ A list of relative column widths. The special value
"auto" delegates the determination of column widths to the backend
(LaTeX, the HTML browser, ...).
+ The default depends on the writer.
+ The html5_ and manpage_ writers default to *"auto"*, the html4_ and
+ LaTeX_ writers default to equal-width columns. [#widths-default]_
+
.. [#CSV] CSV (comma separated values) is a common data format generated
by spreadsheet applications and commercial databases. Despite the
"comma" in its name, the field delimiter_ may be any Unicode character.
-.. [#tab-expansion] Note, that tabs can be used as separator only in
- external files because hard tabs in the directive content are
- `converted to spaces`__ before it reaches the CVS reader.
+.. [#tab-expansion] Note, that *tabs* can be used as separator only in
+ external files because hard tabs in the reStructuredText source are
+ `converted to spaces`__ before parsing.
__ restructuredtext.html#whitespace
@@ -1056,7 +1064,12 @@
.. [#] Before DocutilsĀ 0.21, the header option used a hard-coded
CSV dialect with the backslash as escape character.
+.. [#width-from-widths2] The `LaTeX writer defaults to a table width
+ of 100%`__ unless the ``width`` or ``widths`` option is set.
+ __ ../../user/latex.html#table-width
+
+
.. _list-table:
List Table
@@ -1119,17 +1132,19 @@
.. _table width:
``width`` : length_ or percentage_ of the current line width
- Sets the width of the table to the specified length or percentage
- of the line width. If omitted, the renderer determines the width
- of the table based on its contents or the column ``widths``.
+ The width of the table.
+ By default, the renderer determines the width of a table
+ from its contents. [#width-from-widths2]_
``widths`` : `list of integers`_ or "auto"
- A list of relative column widths.
- The default is equal-width columns (100%/#columns).
-
+ A list of relative column widths. The special value
"auto" delegates the determination of column widths to the backend
(LaTeX, the HTML browser, ...).
+ The default depends on the writer.
+ The HTML5_ and manpage_ writers default to *"auto"*, the html4_ and
+ LaTeX_ writers default to equal-width columns. [#widths-default]_
+
.. TODO
Add option ``missing-cells`` with keywords "strict", "fill", "span"?
(cf. [feature-requests:#103])
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-07-29 16:12:15 UTC (rev 10189)
+++ trunk/docutils/docs/user/config.rst 2025-07-30 08:22:32 UTC (rev 10190)
@@ -1788,7 +1788,7 @@
New in Docutils 0.18.
-__ latex.html#table-style
+__ latex.html#table-width
literal_block_env
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2025-07-29 16:12:15 UTC (rev 10189)
+++ trunk/docutils/docs/user/latex.rst 2025-07-30 08:22:32 UTC (rev 10190)
@@ -1664,7 +1664,7 @@
A pre-configured *table style* can be globally selected via the table_style_
setting or set for individual tables via a `class directive`_ or the
-``class`` option of the `table directive`_.
+``class`` option of the `table directives`_.
Supported values:
@@ -1672,39 +1672,103 @@
Borders around all cells.
booktabs
- A line above and below the table and one after the head.
+ Use the booktabs_ package for publication quality tables (no vertical rules).
borderless
No borders around table cells.
-colwidths-auto
+_`colwidths-auto`
Column width determination by LaTeX.
- Overridden by the `table directive`_'s ``widths`` option.
+ Overridden by the `table directive option`_ ``widths``.
- .. warning::
+ .. Caution::
+ `Auto-sized columns`_ work only with simple cell content.
- ``colwidths-auto`` is only suited for tables with simple cell content.
-
- LaTeX puts the content of auto-sized columns on one line (merging
- paragraphs) and may fail with complex content.
-
.. eventually in future
align-left, align-center, align-right
Align tables.
-By default, *column widths* are computed from the source column widths.
-The `legacy_column_widths`_ setting selects the conversion algorithm.
-Custom column widths can be set with the ``widths`` option of the `table
-directive`_.
+.. _booktabs: https://ctan.org/pkg/booktabs
-See also the section on problems with tables_ below.
-.. _new_column_widths:
+.. _table width:
+
+table width and column widths
+-----------------------------
+
+To support automatic line breaks, standard LaTeX tables need to know the
+column widths. Therefore, the LaTeX writer determines default values for
+both, relative column widths and the total width of a table from the
+table's ``colwidth`` [#fn:colwidth]_ values. [#fn:table-width]_
+The algorithm works sufficiently well in typical use cases. However,
+there are cases where the table layout requires manual intervention,
+for example:
+
+* Tables where the cells contain only numbers or short text look better
+ with `auto-sized columns`_.
+
+* If the input table contains verbose markup syntax, column widths in the
+ source may be bad indicators for output column widths.
+
+* Columns may become too narrow in tables that are nested inside lists,
+ quotes, or similar.
+
+To improve the table layout, you may:
+
+* Use the `table directive option`_ ``width`` to set the table width
+ to a custom `length <length units_>`__ or percentage_ of the current
+ line width.
+
+* Adjust the table column widths in the source document or use the
+ `table directive option`_ ``widths`` to specify column widths.
+
+ .. _auto-sized columns:
+
+* Set the `table directive option`_ ``widths`` to the value *"auto"* or
+ select the `table style`_ "colwidths-auto_" to let LaTeX determine
+ table and column widths from the table content.
+
+ .. Caution::
+ Auto-sized columns only work with simple cell content.
+
+ LaTeX sets cell content in auto-sized columns in one line (merging
+ paragraphs) and fails with other block level content.
+
+The `legacy_column_widths`_ setting provides backwards compatibility with
+the (faulty) legacy algorithm.
+
+.. [#fn:colwidth]
+ Docutils stores the column widths in the reStructuredText
+ `table markup`_ (in characters) in the colwidth_ attribute
+ of the table column specifications.
+ (The colwidth_\ s of a `list table`_ or `CSV table`_ with :math:`n`
+ columns default to :math:`w_i = 100\text{ā«½}n`.)
+ The ``widths`` `table directive option`_ can be used to provide custom
+ values.
+
+.. [#fn:table-width]
+ The default width :math:`w` of a table with :math:`n` columns and
+ ``colwidth`` [#fn:colwidth]_ values :math:`w_i` is computed using
+ the equation
+
+ .. math::
+ w = \frac{100\,\%}{40} \left( n + \sum_{i=1}^n w_i \right)
+
+ with an upper limit of 100%.
+
+ .. For details see `docutils.writers.latex2e.Table.get_colspecs()`.
+
+.. _colwidth: ../ref/doctree.html#colwidth
+.. _CSV table: ../ref/rst/directives.html#csv-table
+.. _document tree: ../ref/doctree.html
.. _legacy_column_widths: config.html#legacy-column-widths
+.. _list table: ../ref/rst/directives.html#list-table
+.. _percentage: ../ref/rst/restructuredtext.html#percentage-unit
+.. _table directives: ../ref/rst/directives.html#tables
+.. _table directive option: ../ref/rst/directives.html#table-options
+.. _table markup: ../ref/rst/restructuredtext.html#tables
.. _table_style: config.html#table-style-latex-writers
-.. _"widths" option:
-.. _table directive: ../ref/rst/directives.html#table
table of contents
@@ -2163,10 +2227,10 @@
Tables
``````
-* Too wide tables (cf. `bug #422`_):
+* Too wide tables:
- Try the new_column_widths_ setting or use the `"widths" option`_ to
- manually set the table column widths.
+ - Turn off the legacy_column_widths_ setting (cf. `bug #422`_)
+ or manually set the `table width`_.
* Table cells with both multirow and multicolumn are currently not possible.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins