[gentoo-user] Re: ridiculously wide handbook pages

[Grant Edwards]

On 2010-09-30, Grant Edwards <grant.b.edwards@×××××.com> wrote:
> On 2010-09-30, Darren Kirby <bulliver@×××××.com> wrote:
>> On Thu, Sep 30, 2010 at 11:13 AM, Grant Edwards
>><grant.b.edwards@×××××.com> wrote:
>>
>>>
>>> I can understand that things like example code blocks or sample
>>> command input/output blocks might need to be wide enough to require
>>> horizontal scrolling of a browser window, but normal text paragraphs
>>> with 160 characters per line?
>>
>> I'm not seeing a problem here. Sure, the lines are long but my screen
>> is large and my resolution is high. A quick play with firefox and konq
>> shows that the text reformats itself quite elegantly when you resize
>> your browser window to say, 2/3 of screen width.
>
> I'm using firefox, and the text doesn't reformat for me.  I just end
> up with a change in the size of the horizontal scrollbar.  Are you
> sure you're looking at the same pages I was talking about?
>
>   http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1
>   http://www.gentoo.org/proj/en/base/embedded/handbook/?part=1&chap=2

OK, I think the problem is caused by "literal" blocks (the ones
containing command-line examples with the light-blue background where
nothing ever wraps).  The _minimum_ line-wrap length for normal text
paragraphs is determined by the _maximum_ line length in a literal
block. Resizing the browser window horizontally only reformats text
_if_ the window is wider than the longest literal block line.  For
many of the pages that requires more screen width than I, for one,
have.

IOW, for any pages with long command line examples (or program output
examples), you end up with very unweildy text paragraphs.

I'm not sure what formatting system the manual pages use (to me the
pages look way too clean, consistent, and neat to be hand-coded).  
Using asciidoc, for example, you avoid this problem by specifying a
maxmimum width for normal text blocks so that they won't end up being
arbitrarily long depending on what command line examples you happen to
have in the document.  I find 40em to be a nice max width:

  asciidoc -a data-uri -a toc -a max-width=40em <input-file>

>> I think that's a better solution than imposing some arbitrary line
>> length on everyone no matter their screen size and resolution.

No, I wouldn't want to impose an arbitrary line lenth on everybody,
but that's exactly what we have now.  The arbitrary line length that's
imposed is (length >= max(lengths-of-lines-in-literal-blocks)).

For pages without any wide literal blocks, it's not an issue, and the
normal paragaphs reflow as they should.  For most of the manual pages
that I look at, it is an issue.

I'd prefer to have the line lengths determined by the browser window,
and that's not what we have now for much of the manual.

-- 
Grant Edwards               grant.b.edwards        Yow! Edwin Meese made me
                                  at               wear CORDOVANS!!
                              gmail.com