Bad wrapping in some tables

Bad wrapping in some tables

[Daniel Lundberg Pedersen]

I've noticed some bad wrapping happening in tables, seemingly only in the Media
docs, but that's also where I look the most, after v7.1.

See:

https://www.kernel.org/doc/html/v7.1/userspace-api/media/v4l/vidioc-create-bufs.html#c.V4L.v4l2_create_buffers

Compared to:

https://www.kernel.org/doc/html/v7.0/userspace-api/media/v4l/vidioc-create-bufs.html#c.V4L.v4l2_create_buffers

Other tables have also changed, but they don't end up this bad, e.g:

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

I've bisected it to be f2679ac773899f5fdea0b68d5077eef5f88dfd42 that has caused
the change, and I did try some quick changes to see if I could fix it for the
tables, but I didn't get any positive results.


Regards Daniel

Re: Bad wrapping in some tables

[Manuel Ebner]

On Tue, 2026-07-07 at 18:39 +0200, Daniel Lundberg Pedersen wrote:
> I've noticed some bad wrapping happening in tables, seemingly only in the Media
> docs, but that's also where I look the most, after v7.1.
> 
> See:
> 
> https://www.kernel.org/doc/html/v7.1/userspace-api/media/v4l/vidioc-create-bufs.html#c.V4L.v4l2_create_buffers
> 
> Compared to:
> 
> https://www.kernel.org/doc/html/v7.0/userspace-api/media/v4l/vidioc-create-bufs.html#c.V4L.v4l2_create_buffers
> 
> Other tables have also changed, but they don't end up this bad, e.g:
> 
> https://www.kernel.org/doc/html/v7.1/process/debugging/kgdb.html#run-time-parameter-kgdbreboot
> 
> I've bisected it to be f2679ac773899f5fdea0b68d5077eef5f88dfd42 that has caused the
> change

Well done.

Please use git commit description style:  commit f2679ac77389 ("docs: allow inline
literals in paragraphs to wrap to prevent overflow")

I added the people involved in this patch to cc.

Thanks
 Manuel

> and I did try some quick changes to see if I could fix it for the
> tables, but I didn't get any positive results.
> 
> 
> Regards Daniel

Re: Bad wrapping in some tables

[Jonathan Corbet]

Daniel Lundberg Pedersen <dlp@qtec.com> writes:

> I've noticed some bad wrapping happening in tables, seemingly only in
> the Media docs, but that's also where I look the most, after v7.1.
>
> See:
>
> https://www.kernel.org/doc/html/v7.1/userspace-api/media/v4l/vidioc-create-bufs.html#c.V4L.v4l2_create_buffers
>
> Compared to:
>
> https://www.kernel.org/doc/html/v7.0/userspace-api/media/v4l/vidioc-create-bufs.html#c.V4L.v4l2_create_buffers
>
> Other tables have also changed, but they don't end up this bad, e.g:
>
> https://www.kernel.org/doc/html/v7.1/process/debugging/kgdb.html#run-time-parameter-kgdbreboot
>
> I've bisected it to be f2679ac773899f5fdea0b68d5077eef5f88dfd42 that
> has caused the change, and I did try some quick changes to see if I
> could fix it for the tables, but I didn't get any positive results.

For future reference, it really does help to copy the maintainer and the
author of the patch.

The patch in question tweaked our CSS thusly:

> +code.docutils.literal span.pre {
> +    white-space: normal;
> +    overflow-wrap: anywhere;
> +}

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.

I've just made the attached revert - thanks for the report!

jon

From 1afefde902c5267d1197da8a3b039354ed771d37 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Tue, 7 Jul 2026 11:34:47 -0600
Subject: [PATCH] Revert "docs: allow inline literals in paragraphs to wrap to
 prevent overflow"

This reverts commit f2679ac773899f5fdea0b68d5077eef5f88dfd42.

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

Reported-by: Daniel Lundberg Pedersen <dlp@qtec.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/sphinx-static/custom.css | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 5aa0a1ed9864..2e019c8f8a56 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -156,15 +156,6 @@ div.language-selection ul li:hover {
     background: #dddddd;
 }
 
-/*
- * Let long inline literals in paragraph text wrap as needed to prevent
- * overflow.
- */
-code.docutils.literal span.pre {
-    white-space: normal;
-    overflow-wrap: anywhere;
-}
-
 /* Let rendered reference links in tables wrap when needed. */
 div.body table.docutils a.reference {
     overflow-wrap: anywhere;
-- 
2.54.0

Re: Bad wrapping in some tables

[Rito Rhymes]

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

Re: Bad wrapping in some tables

[Hans Verkuil]

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

Re: Bad wrapping in some tables

[Mauro Carvalho Chehab]

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

Re: Bad wrapping in some tables

[Daniel Lundberg Pedersen]

Hi

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.

Sorry about that, I'll remember that for next time.

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

I don't mind testing some stuff if you want me to, but as Hans mentions 
the media docs is full of tables which have these issues, from a quick
check, almost all sub-pages of the Function Reference are affected:

https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/user-func.html

> 
> Rito


Regards Daniel

Re: Bad wrapping in some tables

[Mauro Carvalho Chehab]

On Fri, 10 Jul 2026 14:38:06 +0200
Daniel Lundberg Pedersen <dlp@qtec.com> wrote:

> Hi
> 
> 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.  
> 
> Sorry about that, I'll remember that for next time.
> 
> [...]
> > 
> > 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.  
> 
> I don't mind testing some stuff if you want me to, but as Hans mentions 
> the media docs is full of tables which have these issues, from a quick
> check, almost all sub-pages of the Function Reference are affected:
> 
> https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/user-func.html

On media, I guess the more complex tables with long widths are the pixfmt 
ones like those:

	https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/pixfmt-rgb.html
	https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/pixfmt-packed-yuv.html

It is a good place to check for issues like that.

Please see the patch I submitted:

	https://lore.kernel.org/linux-doc/1950557405f1150acb1de50de1801f2413223b87.1783673996.git.mchehab+huawei@kernel.org/

It moves width support at the html output from previous
millennium SVGA-resolutions era to modern age.

-- 
Thanks,
Mauro

Re: Bad wrapping in some tables

[Jonathan Corbet]

"Rito Rhymes" <rito@ritovision.com> writes:

> Reason 2: the real culprit here is this:
>
> Table mobile responsiveness in general in the Linux kernel
> documentation is systemically pathological.

I honestly have to question how important that is to us.  How many
people are really trying to make use of the kernel documentation on
small-screen devices?  This is the kind of information you need when you
have editor and terminal windows open.

Making small screens work better is fine on its own, but I don't think
it should be done at the cost of proper rendering on the sort of devices
that developers actually use.  There are limits to which we want to
develop and maintain our own custom theme for a use case that, I
believe, is pretty rare.

Thanks,

jon