Re: Bad wrapping in some tables

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Fri, 10 Jul 2026 10:11:20 +0200
Hans Verkuil <hverkuil+cisco@kernel.org> wrote:

> 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.

Breaking up literals is more important on PDF output, if one wants to print
the documentation.

> 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.

IMO what should be changed is the maximum column limit at the html CSS profile.

Right now it sets max-width to 800px, which comes from basic.css:

	div.body {
	    min-width: inherit;
	    max-width: 800px;
	}

This is quite small on my monitor (it is a wide monitor with 5120px).

I would override this to none, to let it auto-adjust it to the actual
monitor limits.

Thanks,
Mauro