forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Brian Topping" <>
Subject Documentation widths
Date Sat, 01 Jun 2002 05:57:08 GMT
Hi all,

I've been doing some reading lately of Cocoon docs on my laptop, and have been wondering why
the widths of the documents have grown so wide.  My laptop screen is 1024 pixels wide, and
the main body text column is often wider than that.  I suppose this will also cause problems
when generating portrait-orientation PDF.  The result is you have to horizontally scroll the
window to a point where you get most of the text on the screen and then just guess what it
says from the context of what you are reading.  It's too difficult to read a document and
scroll back and forth horizontally as you make your way down the page.

Some of you may be aware of this problem, but I wanted to bring it up as an issue anyway since
I did some sleuthing on it.

Basically, the problem isn't with the master stylesheet, it's a problem with data wrapped
with the <source> tag.  Usually this tag is used for configuration files and source

Since this tag uses the HTML <pre> element and the <pre> element does not wrap,
the table cell containing the source tag becomes the widest element.  All it takes is one
<source> block that is very wide, and the entire document cannot be reduced in width.
 At least on Cocoon, the body text is able to resize and the header will resize, but the body
text is contained as a table element as well, and the minimum table element width is the size
of the largest element in the column.

I see four potential solutions so far, and I don't like any of them.  I hope there are more:

1) Be very careful with the width of the content in <source> tags.  This seems prone
to problems as people forget when they are creating documents and requires going through all
the docs to fix them.  To encourage this, maybe a build warning could be emitted when the
width gets outrageous.

2) Add <width> tags to the HTML output cells that do not contain <source> from
within the stylesheets.  This would penalize people who had wide screens and preferred to
use the width, but studies show that text typeset in columns that are too wide is harder to
read than narrower columns anyway. 

3) Add a preprocessor to the <source> template that reflows the contents to a narrower
width.  This one sounds ugly because the preprocessor would have to understand where to reflow
(i.e. not chop words, indent the next line nicely...)  Once again, triggering the reflow could
cause a build warning so someone would know to fix it.

4) Change the font size in the <source> template to something really small.  Ick.

Does this bug anyone else besides me?  The documents are almost unreadable on a laptop at
this point.

I'm tossing it into the mix here first to see what the experts think, but willing to put some
effort into updating the tree if a decision can be made on what to do.

thanks for your time,


View raw message