Latex writer should use tabu package and longtabu instead of longtable (patch available)

[callegar]

Longtable makes it impossible to have 'paragraph type' table entries with automatically computed width.

However, this is an absolute necessity in order to correctly process things line autosummary tables.
Otherwise, one gets a latex document causing tons of overfull boxes and with text that is unreadable because it extends out of the page.

The tabu package, loaded together with longtable, provides a longtabu environment that simultaneously provides the features of longtable and tabularx.

Hence, the latex writer should be patched to use tabu. For instance, setting

latex.LaTeXTranslator.default_elements['longtable'] = (
    r'\usepackage{longtable}' + '\n' +
    r'\usepackage{tabu}')

and then, in depart_table, having something like

    if self.table.longtable:
        self.body.append('\n{\\tabulinesep=0.5ex%\n\\begin{longtabu}')
        endmacro = '\\end{longtabu}}\n\n'

with this, the autosummary module can also be patched in the get_table function to set as column specifiers

table_spec['spec'] = 'lX[,l]'

instead of using ll

[birkenfeld]

I'm always up for better table handling. If tabu can do that, we'll definitely have a look at it.

[FranklinYu]

Would package tabu be obsolete since the author is going to change the user commands?

[callegar]

Yes, tabu is going to be superseded, but no one really knows when. The author said in June 2013 that the new package was due to be out by the end of the Summer, but it is not there.
In the meantime:

• One can expect that when the new package comes out it will take a new name, while the old package will remain around with the old name, as it is in the CTAN tradition.
• The current tabu package works well enough for the current use in sphinx
• The current sphinx behavior based on longtable is quite broken when using autosummary tables
• The current tabu closely mimics the interface of tabular, so even if the newer version changes almost everything it is unlikely that it will alter the user interface too much.

So, my opinion is that sphinx should move to tabu asap and move again to the newer tabu when it finally comes out, otherwise all those using autosummary tables will start monkey patching sphinx via extensions to get something usable.

[callegar]

ltablex may be an alternative too.

[FranklinYu]

• Everyone would expect the new package come with a new name, but I don't think we should rely on it since the author did not prove this.
• Indeed tabu is mostly tabular, but changes in the extra commands may change the implementation structure, and the author needs additional (possibly significant) time to fix it.
• ltablex is a good alternative, I believe.

[sergiocallegari]

Just a quick note to record that a new version of tabu has still not arrived.

Since the issue with tables in latex that generate bad boxes is still there, I think that we may want to consider tabu as is, rather than waiting for the new version (or use ltablex).

Should the tabu way be preferred, to be protected from the author changing tabu in an incompatible way retaining the name (bad), could shipping the current tabu.sty with sphinx be an acceptable approach?

[jfbu]

A quick note to record that the latest update by the LaTeX team to array package has not been (so far) followed up by tabu which thus is currently broken.

This incident illustrates why Sphinx must remain conservative in this area, at least in its default LaTeX configuration; sure, Sphinx should offer a more modular structure in LaTeX, allowing e.g. users to painlessly adopt tabu/longtabu as their table rendering package, or at least make it not too complicated for a Sphinx extension to provide this, but this requires significant investment of time, and achieving compatibility with third-party LaTeX packages such as tabu which may become broken or unmaintained should not be part of core Sphinx.

The main reasons why Sphinx did not adopt tabu/longtabu in the past were:

• necessity to have a recent TeX installation. Admittedly with upcoming Sphinx 2.0, the requirement is raised to TeXLive 2015 thus allowing usage of "modern" LaTeX packages. Paradoxically though, tabu may perhaps need to be considered unmaintained hence unusable nowadays,

• the fact that tabu author announced he had been working on a new version keeping the same name but which would not keep the same user interface; maybe this was said in jest, but some LaTeX people reacted with overt hostility to this announcement by (talented) tabu author, and there was a clash of some sort, and as a result it is not clear if we can consider tabu as maintained or unmaintained package.

• iirc, problems with supporting code-blocks in table-cells.

[tk0miya]

Is there any chance to support tabu in sphinx-core? If my understanding is right, there are no chance at present. If true, I'd like to mark this as "wontfix".
@jfbu What do you think?

[jfbu]

This issue was formulated as using tabu/longtabu by Sphinx core. As such I agree with "wontfix" for the reasons above.

Let me add one element, although I have not had time to make a full review of the tabu situation again: right now I tested with TeXLive 2017 that the tabu* which is supposed to be usable with Verbatim content does not seem to work when fncyvrb's Verbatim is used with commandchars option. This does not work:

\documentclass{article}
\usepackage{fancyvrb}
\usepackage{tabu}
\begin{document}

\begin{tabu*}to\linewidth{|XX|}
A&
\begin{Verbatim}[commandchars=\\\{\}]
And this is a complete
Verbatim environment
\end{Verbatim}
\\
\end{tabu*}

\end{document}

only after removing [commandchars=\\\{\}] does it work. And we absolutely need it as Sphinx produces this kind of mark-up:

\begin{sphinxVerbatimintable}[commandchars=\\\{\}]
\PYG{k}{def} \PYG{n+nf}{foo}\PYG{p}{(}\PYG{n}{x}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{return} \PYG{n}{x}\PYG{o}{*}\PYG{o}{*}\PYG{l+m+mi}{2}
\end{sphinxVerbatimintable}

in order for the \PYG macro to expand and provide syntax highlighting. (the environment contents is output of Pygmentize library)

from original source

.. list-table::

   * - .. code-block:: python

          def foo(x):
              return x**2

     - B

   * - U
     - V

I did not investigate the root cause of why tabu* does not work immediately with our usage of Verbatim but this and the other things mentioned is enough to conclude sphinx-core will not opt for tabu/longtabu as table rendering LaTeX interface in near future.

More promising regarding the problem with computation of column widths is to do it ourself via Python code, I started this (#4507) but then I feared some complications with substitutions and basically I have not had the time to push it further so far.

[tk0miya]

Thank you for comment. Okay, let's mark this as "wontfix".

Note: It does not mean "never". We'll can reconsider when somebody would send excellent PR for us or situation changed.

Thank you for proposal.

[jfbu]

For future reference, the problem with Verbatim is blocking. tabu is simply incompatible with incorporating code-blocks in table cells using Pygmentize output for highlighting code.

I raised the issue upstream tabu-issues-for-future-maintainer/tabu#3.