Re: Bad wrapping in some tables

[Hans Verkuil <hverkuil+cisco@kernel.org>]

On 10/07/2026 08:55, Rito Rhymes wrote:
> 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
> 

FYI: the Media subsystem userspace API is full of tables, e.g.:

https://docs.kernel.org/userspace-api/media/v4l/vidioc-enuminput.html
https://docs.kernel.org/userspace-api/media/cec/cec-ioc-receive.html

There are many, many more of those.

Currently it is basically unreadable due to the breaking up of the literals.

Hopefully this can be fixed. I only noticed this issue yesterday, so it was
good to see your email so I know why it changed.

We're well aware that the tables in the media subsystem do not work well on
small screens. The only workable solution would be to move away from tables
and format it differently. And that's not going to happen as that would be a
massive job.

Regards,

	Hans