Bug 16579 - documentation page layout/style breaks wrapping to fit browser window
Summary: documentation page layout/style breaks wrapping to fit browser window
Status: RESOLVED DUPLICATE of bug 55383
Alias: None
Product: Tomcat 7
Classification: Unclassified
Component: Documentation (show other bugs)
Version: trunk
Hardware: All All
: P3 enhancement (vote)
Target Milestone: ---
Assignee: Tomcat Developers Mailing List
URL: http://jakarta.apache.org/tomcat/tomc...
Depends on:
Reported: 2003-01-30 05:16 UTC by Daniel B.
Modified: 2013-08-07 21:21 UTC (History)
1 user (show)


Note You need to log in before you can comment on or make changes to this bug.
Description Daniel B. 2003-01-30 05:16:01 UTC
Could the page layout for Tomcat documentation please be reconsidered?
It stops _all_ regular text from wrapping to fit the window when _any_ 
line of fixed-width text is wider than the window. 

Specifically, using an HTML table to put navigation links to the left of
the main page text forces the browser to ignore the width of the browser 
window and wrap wrappable text to match the width of the longest fixed-width
line.  Then, when the user uses a window that is not as wide as the longest
line, the user must scroll horizontally to read _every_ line.  

(If the browser weren't constrained by the table, it could wrap all the
wrappable text to fit the window, and only the long, fixed-width lines 
would require horizontal scrolling to see.)

I realize that avoiding putting the body text inside a table may prevent
having a list of navigation links on the left.

However, PLEASE re-consider the layout.  

One option is to put navigation elements at the top of the page.  (You don't
need a table to do that, so the body text doesn't need to be in a table, so
wrappable text can still wrap to fit the browser window.)

Another thing to consider is whether every detail page really needs a list of 
links to every sibling page.  (Books don't have a copy of the table of contents
at the start of each chapter.)  Each detail page needs only an up link to one
common index page that lists the various detail pages. (Of course, you'd
probably have more links that just that absolute minimum.))

Consider some precedents:

Sun's JavaDoc layout for a class:
- Class description text and member description text wraps to fit even very
  narrow windows, even if summary tables don't fit within the window.
  (Also, notice that each summary table is independent.  If one is too wide
  and requires horizontal scrolling, the others can still fit.)
- The page for one class is not cluttered with links to a bunch of sibling
- The page has an up link to the page for the containing package, which does
  list the sibling classes of the given class.
- The navigation is on the top, not the left.  (That allows most of the text
  to wrap to fit within the window width.)

Linux HOW-TO documents in HTML generated from DocBook:
- Wrappable text wraps to fit the browser window, even if some fixed-width text
  or images are wider.
- There are some basic Next/Previous/section number links at the top.
- The pages are not cluttered with multiple links to sibling documents, just
  a simple up link or two.

Relatedly, when thinking about page widths, please don't assume that all
readers use full-screen browser windows.  Especially for technical 
documentation, readers are likely to be reading documentation in one window
and using it (e.g., editing code, running some tool) in another window.

Also note how wide pages such as
http://jakarta.apache.org/tomcat/tomcat-4.0-doc/jndi-resources-howto.html are.
On my system, that page requires a 1086-pixel-wide browser window to display
the entire width!  Display just the body does fit in 800 pixels, but you'd
need 1600 pixels across to see the text without scrolling on one side of your
screen and edit something in a same-sized window on the other side.
Comment 1 Christoph Seibert 2003-01-30 09:23:03 UTC
Yes, having to scroll horizontally is one of the top annoyances in web browsing.

See also bug #15915 that I added some time ago, which is also concerned with
table-based layout. Even if using a table doesn't automatically mean that the
text cannot wrap, a standards-based layout using CSS for presentation has many
benefits for all kinds of users. As you can see in the attachment I created for
that bug, the visual appearance of the page in standards compliant browsers does
not have to change. However, the page becomes more accessible for users in
non-visual browsing situations, as well as in visual browsing environments from
PDAs to large screens.

I'm willing to work on this, but so far haven't had any feedback on this matter.
Comment 2 Mark Thomas 2004-03-06 16:36:00 UTC
I agree that the changes described here are worthy of consideration. It should 
be noted that the chances of changes being made to documentation are greatly 
increased if a patch is provided.

For your information, the tomcat docs are written in xml and then transformed 
into static html. Patches need to be against the .xml files or tomcat-docs.xsl
Comment 3 Mark Thomas 2011-03-07 05:18:25 UTC
Still want to look at this at some point. Moving to Tomcat 7. Some more things to consider:
- Tomcat 7 docs
- Tomcat website
- the new ASF CMS
- the new Tomcat 7 start page
Comment 4 Mark Thomas 2013-08-07 21:21:52 UTC
The duplicate has a better description and some clear action points so lets track progress there.

*** This bug has been marked as a duplicate of bug 55383 ***