Re: Bad wrapping in some tables

["Rito Rhymes" <rito@ritovision.com>]

I just got caught up to speed, reviewing the links, the regression, the
prior state and other relevant context.

Daniel, thanks for pointing out the regression. As Jon said, it's
always good to inform the author of the patch, and I'd have been happy
to discuss and test out solutions with you.

> That overflow-wrap line is the problem. The patch was trying to
> improve overflow from some literal blocks, but it does seem that the
> cure is worse than the disease.

> This change causes truly unreadable breaking of literal strings in a
> number of settings.

Can anyone provide any examples of issues happening outside of tables?

If not, that suggests the fix is working fine except inside tables,
which means a targeted fix for tables is possible.

The intention of the fix is that inline literals in regular text bodies
that have a generally defined (max) width will respect that width and
not exceed it and cause overflow. It's serving that purpose and is a
sensible default behavior because it is often used like text in text
bodies and surrounded by other text, thus we make it also behave like
text.

I don't believe a reversion is the right answer, for two reasons.

Reason 1:

Reverting the fix restores the issues outside the tables it previously
fixed, and fixes some of the tables, but makes others just as
unreadable.

In the second example Daniel provided, there is a two column table
spanning the full width of the page on mobile viewport sizes without
overflowing. The left column is inline literals only, the right column
is regular text.

After my fix:
https://www.kernel.org/doc/html/v7.1/process/debugging/kgdb.html#run-time-parameter-kgdbreboot

The left column of inline literals wraps down into vertical text and is
unreadable, because the column has no minimum width and expects the
contents to set the width, but it wraps immediately. That's a problem.
The right column text is readable, though it does some wrapping for a
few words.

Before the fix:
https://www.kernel.org/doc/html/v7.0/process/debugging/kgdb.html#run-time-parameter-kgdbreboot

The issue is as bad or worse. The left column is fully readable and
spans literals as far as needed, but it's crushing the right column and
forcing that into vertical text (maybe 2-3 characters wide), making
that column unreadable.

What's worse, unreadable vertical text as inline literals or as regular
text? Regular text is worse because it's meant to be descriptive, but
having either one is unacceptable.

Reason 2: the real culprit here is this:

Table mobile responsiveness in general in the Linux kernel
documentation is systemically pathological.

Many if not most of the tables on smaller screens overflow page width
and break the page margins. And this page is another example of
pathological table behavior where the table doesn't overflow and
break the page margins, it respects the page margin width, but
instead makes the content inside unreadable as vertical text, either
from the string literal wrapping or from the text wrapping. Neither
my current fix nor the reverted state resolves that issue.

The best solution:
Make targeted changes to the tables to make them fundamentally behave
better on smaller screen sizes.

I began this effort with:
[PATCH v3] docs: wrap generated tables to contain small-screen overflow

Jon hadn't followed up after testing out the fix with CSS and my
explaining why the wrapper was the better approach, because it prevented
regressions. That fix is a start, but more would need to be done.

If Daniel is willing to help test out table fixes and provide examples
of regressions, and if Jon has the bandwidth to review my patch
submissions to improve the tables, I am willing to tackle this systemic
issue, which will result in this issue being resolved as well.

Rito