DO NOT REPLY [Bug 16579] New: - documentation page layout/style breaks wrapping to fit browser window

[bu...@apache.org]

DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG 
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://nagoya.apache.org/bugzilla/show_bug.cgi?id=16579>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND 
INSERTED IN THE BUG DATABASE.

http://nagoya.apache.org/bugzilla/show_bug.cgi?id=16579

documentation page layout/style breaks wrapping to fit browser window

           Summary: documentation page layout/style breaks wrapping to fit
                    browser window
           Product: Tomcat 4
           Version: 4.0 Final
          Platform: All
               URL: http://jakarta.apache.org/tomcat/tomcat-4.0-doc/jndi-
                    resources-howto.html
        OS/Version: All
            Status: NEW
          Severity: Normal
          Priority: Other
         Component: Unknown
        AssignedTo: tomcat-dev@jakarta.apache.org
        ReportedBy: dsb@smart.net


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
  classes.
- 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.

---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org