LaTeX: better choice for \tymax parameter (#13711)

doc/usage/restructuredtext/directives.rst

@@ -1499,8 +1499,31 @@ Check the :confval:`latex_table_style`.
    using ``tabulary`` is that it tries to compute automatically (internally to
    LaTeX) suitable column widths.
 
-   :rst:dir:`tabularcolumns` can serve to provide one's own "colspec" choice.
-   Here is an advanced example:
+   The ``tabulary`` algorithm often works well, but in some cases when a cell
+   contains long paragraphs, the column will be given a large width and other
+   columns whose cells contain only single words may end up too narrow.  The
+   :rst:dir:`tabularcolumns` can help solve this via providing to LaTeX a
+   custom "alignment preamble" (aka "colspec").  For example ``lJJ`` will be
+   suitable for a three-columns table whose first column contains only single
+   words and the other two have cells with long paragraphs.
+
+   .. note::
+
+      Of course, a fully automated solution would be better, and it is still
+      hoped for, but it is an intrinsic aspect of ``tabulary``, and the latter
+      is in use by Sphinx ever since ``0.3``...  It looks as if solving the
+      problem of squeezed columns could require substantial changes to that
+      LaTeX package.  And no good alternative appears to exist, as of 2025.
+
+   .. hint::
+
+      A way to solve the issue for all tables at once, is to inject in the
+      LaTeX preamble (see :confval:`latex_elements`) a command such as
+      ``\setlength{\tymin}{1cm}`` which causes all columns to be at least
+      ``1cm`` wide (not counting inter-column whitespace).  Currently, Sphinx
+      configures ``\tymin`` to allow room for three characters at least.
+
+   Here is a more sophisticated "colspec", for a 4-columns table:
 
    .. code-block:: latex
 

sphinx/texinputs/sphinxlatextables.sty

@@ -267,7 +267,7 @@
 %
 % configuration of tabulary
 \setlength{\tymin}{3\fontcharwd\font`0 }% minimal width of "squeezed" columns
-\setlength{\tymax}{2\textwidth}% allow enough room for paragraphs to "compete"
+\setlength{\tymax}{3000pt}% allow enough room for paragraphs to "compete"
 %
 % MEMO: tabulary initially renders cell contents "horizontally" to measure
 %       them and compare their relative importance.  Its goal is to choose the
@@ -284,11 +284,14 @@
 %       the initial horizontal width for "varwidth". In the first tabulary
 %       pass, \sphinxcolwidth is configured (by us) to use \tymax.
 %
-%       During testing, it was determined that our former 10000pt setting for
-%       \tymax could cause "Dimension too large" TeX error if two columns or
-%       more contained such cells.  So we use now 2\textwidth which is more
-%       than 10 times smaller but proves large enough for the tabulary
-%       algorithm to provide reasonable results.
+%       During testing, it was determined that the former 10000pt setting for
+%       \tymax would cause "Dimension too large" TeX error if two columns or
+%       more had cells containing admonitions (such contents does not allow
+%       "varwidth" to reduce the width automatically).  So we use now 3000pt
+%       which allows up to 5 such columns while being large enough for
+%       tabulary algorithm to give good results for cells containing a few
+%       dozen words.  The tabulary default of 2\textwidth proves to be too
+%       small for that.
 %
 % we need access to tabulary's final computed width. \@tempdima is too volatile
 % to hope it has kept tabulary's value when \sphinxcolwidth needs it.