[gentoo-user] Re: ridiculously wide handbook pages

[Grant Edwards <grant.b.edwards@gmail.com>]

On 2010-09-30, Dale <rdalek1967@gmail.com> wrote:
> Grant Edwards wrote:
>
>>>>     http://www.gentoo.org/proj/en/base/embedded/handbook/?part=1&chap=2
>>>>
>>>>        
>>> This one has a horizontal scrollbar but only adjust about a half inch or
>>> so.   It almost fits.
>>>      
>> Are the text paragraphs re-wrapped as you narrow the window?
>
> That one has a scrollbar no matter what.  It appears that section "Code 
> Listing 2.4: Using SH4 cross-compiler" is making it really long.  It has 
> a line in that box that is pretty long.  It's the longest line I saw in 
> the whole page.
>
> So, it appears as someone else posted that the pretty blue boxes set
> the minimum width.

I think that's definitely the issue.

> Whatever is the longest line sets the width.  How would one go about
> changing that I wonder?

I think it can probably be set in the CSS stylesheet, but I'm pretty
fuzzy when it comes to CSS details.

I do know that the web pages I generate with asciidoc don't have this
problem.  In general, the width of the text paragraphs is determined
by the browser width, but listing blocks don't get wrapped and you may
have to scroll over to see the ends of the really wide ones.  I
usually set a max text width as well, so that if you do widen your
browser window to see the really wide listing blocks, you still end up
with text columns that max out at a reasonable width.  Setting a
max-width for text is probably more a matter of taste/style, but I
don't think that anybody can argue that having the minium text width
determined by the maximum listing width is right.

> I know when someone posts a long command on this mailing list, it
> makes it hard to understand when Seamonkey shops it up into two
> lines.

We definitely don't want to wrap things like command lines, config
file listings, code listings, and program input/output.  That's why
you (directly or indirectly) assign them a different CSS style or
object type -- so that you can do things like wrap normal text and not
listings or examples.

> Most people are good enough to post that the command has to be all on
> one line tho.  It appears that a email problem is also a website
> problem too.  When to wrap a line and when not to?

I don't think listings/code/shell-examples should not be wrapped, and
AFAIK, nobody's arguing that they should be.

However, I do assert that normal text paragraphs should be wrapped to
fit within the browser window.

In text-only e-mail messages, there's no way to tell the difference
between the two.

Whatever's generating the HTML/CSS for the Gentoo manual web pages
does know the difference, and should be able to do The Right
Thing(tm). The manual HTML is definitely machine-generated, but I
can't tell you by what at this point, so I can't offer a specific
fix...

-- 
Grant Edwards               grant.b.edwards        Yow! Can you MAIL a BEAN
                                  at               CAKE?
                              gmail.com