tabulary entries in PDF documentation

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

BPO	4145
Nosy	@birkenfeld
Files	Screenshot-collections — High-performance container datatypes — Python v2.6 documentation - Mozilla Firefox.png: HTML renderinf of ABC table Screenshot-library.pdf - Adobe Reader.png: PDF rendering of ABCs collections_pdf.png: collections.pdf - first page (from siplified html) test_latex-2.tex: test LaTEX with defined column width ABCs-2.png: screenshot of ABC table with column width specified

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['type-bug', 'docs'] title = 'tabulary entries in PDF documentation' updated_at = user = 'https://bugs.python.org/wplappert' ``` bugs.python.org fields: ```python activity = actor = 'georg.brandl' assignee = 'none' closed = False closed_date = None closer = None components = ['Documentation tools (Sphinx)'] creation = creator = 'wplappert' dependencies = [] files = ['11827', '11828', '11829', '11834', '11835'] hgrepos = [] issue_num = 4145 keywords = [] message_count = 11.0 messages = ['74969', '74970', '74971', '74972', '74979', '74980', '74983', '74984', '74985', '74990', '74991'] nosy_count = 2.0 nosy_names = ['georg.brandl', 'wplappert'] pr_nums = [] priority = 'normal' resolution = None stage = 'needs patch' status = 'open' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue4145' versions = ['Python 2.7', 'Python 3.3', 'Python 3.4'] ```

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

An the PDF view of the same table

[birkenfeld]

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.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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: \<thead valign="bottom"> \<tr>\<th class="head">ABC\</th> \<th class="head">Inherits\</th> \<th class="head">Abstract Methods\</th> \<th class="head">Mixin Methods\</th> \</tr> \</thead>

So somebody is calculating the column width :) And this somebody - I guess - is Sphinx? Is is possible to do the same for latex? Hmmm.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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|}".

[birkenfeld]

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.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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.

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

Here is the screenshot: ABCs-2.png

[a92fe1cd-6533-414a-83fb-c551d10d6bc9]

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.

[arhadthedev]

Nowadays the overflow happens not in the first but in the second column.