classification
Title: Type: tabulary entries in PDF documentation behavior needs patch Documentation tools (Sphinx) Python 3.4, Python 3.3, Python 2.7
process
Status: Resolution: open georg.brandl georg.brandl, wplappert normal

Created on 2008-10-19 08:46 by wplappert, last changed 2012-10-02 05:52 by ezio.melotti.

Files
File name Uploaded Description Edit
Screenshot-collections — High-performance container datatypes — Python v2.6 documentation - Mozilla Firefox.png wplappert, 2008-10-19 08:46 HTML renderinf of ABC table
Screenshot-library.pdf - Adobe Reader.png wplappert, 2008-10-19 08:47 PDF rendering of ABCs
collections_pdf.png wplappert, 2008-10-19 10:58 collections.pdf - first page (from siplified html)
test_latex-2.tex wplappert, 2008-10-19 22:49 test LaTEX with defined column width
ABCs-2.png wplappert, 2008-10-20 06:14 screenshot of ABC table with column width specified
Messages (11)
msg74969 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 08:46
I wonder if the readabiliy of tables in PDFs can be improved. I take the
example of ABCs. The online documentation can be found at
http://docs.python.org/library/collections.html, the rst source is at
/Doc/library/collections.rst. I'll enclose two png files, which show the
table in HTML format and in PDF format. My PDF reader is Adobe Acrobat
Reader 8.1.2 (Ubuntu), but I also tried xpdf and "Evince Document Viewer
2.22.2". The result is the same that the coulumn width is somehow not
calculated correctly. Any ideas?

PS.: Since I can only upload one file at a time, there will be another
entry soon.
msg74970 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 08:47
An the PDF view of the same table
msg74971 - (view) Author: Georg Brandl (georg.brandl) * Date: 2008-10-19 09:11
The only way to get this right for arbitrary tables is to hand-select
the column widths with a "tabularcolumns" directive.

I'll keep this issue open and optimize these columns step by step.
msg74972 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 10:58
Oh, what a pain, if you have to do it by hand! Is there no other way of
doing it by counting record lengths (in a column) - see below?

Just for the grins of it, I modified collections.html a bit to show more
on the first page. Then I printed a PDF copy of the online web pages. I
include that print as reference.

When looking at the HTML source, I find the following lines at the
beginning of the relevant table:

<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="18%" />
<col width="18%" />
<col width="43%" />
</colgroup>

And the the first table line follows:
</tr>

So somebody is calculating the column width :) And this somebody - I
guess - is Sphinx? Is is possible to do the same for latex? Hmmm.
msg74979 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 16:07
I probed a bit more into HTML output and the column width of tabulary
entries is always present in the HTML output. I don't yet know where
these relative widths are calculated, but I do roughly know how they are
calculated: from the width of table definition in the *.rst files. This
information should be sufficient to define a (relative) width instead of
the generic latex command "\begin{tabulary}{\textwidth}{|L|L|L|L|}".
msg74980 - (view) Author: Georg Brandl (georg.brandl) * Date: 2008-10-19 16:28
The advantage of HTML here is that the browser dynamically adjusts the
column widths to prevent things like in your screenshot from happening.
LaTeX does no such thing. If you tell it that the column width 20%, the
column will not be enlarged to fit if the contained text is longer.

Standard LaTeX tables don't even bother with relative widths: if you
don't explicitly set a width for a column, the column will be stretched
so that all text fits in one line, no matter how wide the table gets.

The L tabulary entry is the best compromise I could find for automatic
handling: it calculates widths based on cell contents. But as said
above, no handling of overlapping text is done, and I couldn't find a
package that helps with that problem.
msg74983 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 20:43
Hi Georg,
the only thing I could find on the net is a reference to:
"\begin{tabular}{p{1in}p{2in}}" at
http://www.cs.cornell.edu/Info/Misc/LaTeX-Tutorial/Tables.html. Assuming
that one knows the effective width of the whole table, one then should
be able to calculate the width of a column based on previous information
in the *.rst files. Since I really don't know anything about LaTeX - and
you certainly do, I should better shut up and don't say anything more.
But indeed, this table business in LaTeX seems to be a bit messy.
msg74984 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 22:43
Hi Georg,
I tried to find a few bones and came up with the following little demo.
I pinched the first few lines from
http://www.latex-community.org/viewtopic.php?f=5&t=910 and set up a
table with defined column widths - see attached file.
msg74985 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 23:31
I used the following values, based on 14cm total width (of the paper)
[it could be a bit more for A4]:
\begin{tabular}{|p{2.94cm}|p{2.52cm}|p{2.52cm}|p{6.02cm}|} - for the ABC
table and reran library.tex completely. The table came out beautifully.
The percent values I took from the equivalent HTML output, based on
collections.rst.

So I think it is possible to calculate column width automatically. Since
it is late, I will not show the PDF output now. Perhaps tomorrow.
msg74990 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-20 06:14
Here is the screenshot: ABCs-2.png
msg74991 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-20 07:40
There are some 200 tables in the 2.6 documentation, 150 alone in
library.tex - and a few less in the 3.0rc1 documentation. So may suggest
a course of action: since most of these tables produces reasonable
results by using your automatic layout, there are only a few to tackle
"manually". You could invent a new keyword e.g. relativecolumnwidth,
which then renders the table in the above style, based on effective
paper width and based on column widths in the *.rst files.
History
Date User Action Args
2012-10-02 05:52:52ezio.melottisetstage: needs patch
versions: + Python 2.7, Python 3.3, Python 3.4, - Python 2.6, Python 3.0
2008-10-21 15:50:28wplappertsetcomponents: + Documentation tools (Sphinx), - Documentation
2008-10-20 07:40:10wplappertsetmessages: + msg74991
2008-10-20 06:14:17wplappertsetfiles: + ABCs-2.png
messages: + msg74990
2008-10-19 23:31:03wplappertsetmessages: + msg74985
2008-10-19 22:49:33wplappertsetfiles: + test_latex-2.tex
2008-10-19 22:48:58wplappertsetfiles: - test_latex-2.tex
2008-10-19 22:43:39wplappertsetfiles: + test_latex-2.tex
messages: + msg74984
2008-10-19 20:43:05wplappertsetmessages: + msg74983
2008-10-19 16:28:26georg.brandlsetmessages: + msg74980
2008-10-19 16:07:13wplappertsetmessages: + msg74979
2008-10-19 10:58:56wplappertsetfiles: + collections_pdf.png
messages: + msg74972
2008-10-19 09:11:25georg.brandlsetpriority: normal
messages: + msg74971
2008-10-19 08:47:50wplappertsetfiles: + Screenshot-library.pdf - Adobe Reader.png
messages: + msg74970
2008-10-19 08:46:44wplappertcreate