classification
Title: Wide literals in the table of contents overflow in documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: eric.araujo, ezio.melotti, georg.brandl, python-dev, scott.dial
Priority: low Keywords: patch

Created on 2008-12-21 16:55 by scott.dial, last changed 2012-11-03 16:30 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
multiprocessing.png scott.dial, 2008-12-21 16:55 screenshot from Firefox 2.0.0.20/Win32 of multiprocessing.html
issue4711.diff ezio.melotti, 2012-09-18 04:49 +word-wrap: break-word;
issue4711.png ezio.melotti, 2012-09-18 04:56 Sample screenshot (before -> after)
Messages (5)
msg78151 - (view) Author: Scott Dial (scott.dial) Date: 2008-12-21 16:55
There is a problem with the table contents with respect to literals that
cannot be word-wrapped. I see this issue here:

http://docs.python.org/dev/2.6/library/multiprocessing.html

The line in the table of contents that reads "The multiprocessing.dummy
module" is broken in that the literal "multiprocessing.sharedctypes"
overflows into the right-hand side. It also ends up underneath the
contents on the right, which makes it extra hard to know what that entry
was about.

This instance may be browser specific, but I think it brings up a more
general question of what should be done with such long literals and how
overflow should be handled. And perhaps even whether it is wise to have
set the width of that div to such a narrow and specific value (230px).

I've attached a screenshot from Firefox 2.0.0.20/Win32 in case it is not
as reproducible as I would expect.
msg89974 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-07-01 11:04
I can see 5 possible solutions here:
1) use "overflow: auto" - an horizontal scrollbar will appear at the
bottom of the sidebar;
2) use "overflow: hidden" - no scrollbar and the content that doesn't
fit in the sidebar won't be visible;
3) allow the sidebar to change its width according to the content - this
may have other negative side-effects;
4) try to break/cut the long items - this may be quite difficult to realize;
5) try some experiment with CSS3's "text-overflow: ellipsis" - it's nice
and it should work on Opera an maybe on FF3.5 too.

Fixing #4965 will probably solve this issue using the first solution, 
"text-overflow: ellipsis" could still be used in addition (it cuts the
word and '...' at the end if the text doesn't fit in the container).

Making the sidebar collapsible (as suggested in #3143) could make the
third option feasible.

The old link doesn't work anymore, this works:
http://docs.python.org/library/multiprocessing.html
msg170634 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-18 04:49
I experimented a bit more with "text-overflow: ellipsis;" but didn't obtain anything good.  With "word-wrap: break-word;" I had better luck, and even if breaking long words might not be the most elegant solution, it looks better than the overflowing text and doesn't hide any content (like text-overflow does).

Georg, what do you think?
msg174644 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2012-11-03 16:14
Screenshot looks great, +1
msg174647 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-03 16:29
New changeset cae65dd22826 by Ezio Melotti in branch '2.7':
#4711: break long words in the docs sidebar to avoid overflow.
http://hg.python.org/cpython/rev/cae65dd22826

New changeset 1046110a819d by Ezio Melotti in branch '3.2':
#4711: break long words in the docs sidebar to avoid overflow.
http://hg.python.org/cpython/rev/1046110a819d

New changeset 1bdab9112e59 by Ezio Melotti in branch '3.3':
#4711: merge with 3.2.
http://hg.python.org/cpython/rev/1bdab9112e59

New changeset c6237edff631 by Ezio Melotti in branch 'default':
#4711: merge with 3.3.
http://hg.python.org/cpython/rev/c6237edff631
History
Date User Action Args
2012-11-03 16:30:58ezio.melottisetstatus: open -> closed
type: behavior -> enhancement
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.4
2012-11-03 16:29:43python-devsetnosy: + python-dev
messages: + msg174647
2012-11-03 16:14:54eric.araujosetmessages: + msg174644
2012-09-18 16:08:28eric.araujosetnosy: + eric.araujo
2012-09-18 04:56:49ezio.melottisetfiles: + issue4711.png
2012-09-18 04:49:06ezio.melottisetfiles: + issue4711.diff
versions: + Python 3.3, - Python 2.6, Python 3.1
messages: + msg170634

keywords: + patch
stage: needs patch -> patch review
2010-07-10 22:59:34terry.reedysetversions: - Python 3.0
2009-07-01 11:05:14ezio.melottisetpriority: low
assignee: georg.brandl -> ezio.melotti
stage: needs patch
versions: + Python 2.6, Python 3.0, Python 3.1, Python 2.7, Python 3.2
2009-07-01 11:04:12ezio.melottisetnosy: + ezio.melotti
messages: + msg89974
2009-07-01 10:20:12ezio.melottilinkissue4965 superseder
2008-12-21 16:55:52scott.dialcreate