Examples of affected pages on docs.kernel.org this patch improves:
  userspace-api/gpio/gpio-handle-set-line-values-ioctl.html
  userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.html
  userspace-api/gpio/gpio-handle-get-line-values-ioctl.html
  userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.html
  userspace-api/gpio/gpio-v2-lineinfo-changed-read.html
  userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.html
  userspace-api/gpio/gpio-v2-line-set-config-ioctl.html
  userspace-api/gpio/gpio-v2-line-get-values-ioctl.html
  userspace-api/sysfs-platform_profile.html

Rito Rhymes (1):
  docs: allow long unbroken headings to wrap and prevent overflow

 Documentation/sphinx-static/custom.css | 7 +++++++
 1 file changed, 7 insertions(+)

-- 
2.51.0

Examples of affected pages on docs.kernel.org this patch improves:
  userspace-api/gpio/gpio-handle-set-line-values-ioctl.html
  userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.html
  userspace-api/gpio/gpio-handle-get-line-values-ioctl.html
  userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.html
  userspace-api/gpio/gpio-v2-lineinfo-changed-read.html
  userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.html
  userspace-api/gpio/gpio-v2-line-set-config-ioctl.html
  userspace-api/gpio/gpio-v2-line-get-values-ioctl.html
  userspace-api/sysfs-platform_profile.html

Rito Rhymes (1):
  docs: allow long unbroken headings to wrap and prevent overflow

 Documentation/sphinx-static/custom.css | 7 +++++++
 1 file changed, 7 insertions(+)

-- 
2.51.0

Some documentation pages contain long headings with unbroken strings
that can exceed the content width and cause page-wide horizontal scroll
overflow.

Allow headings to wrap when needed so they stay within the content
column and do not break page layout.

Browsers do not treat underscores as natural wrap points, so some
code-style headings may still wrap awkwardly. That trade-off is
preferable to allowing horizontal scroll overflow, since headings
should remain immediately visible rather than partly hidden behind
horizontal scrolling.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v2: add Assisted-by attribution and clarify wrapping trade-offs

 Documentation/sphinx-static/custom.css | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..14711c7be 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -8,6 +8,13 @@ div.body h1 { font-size: 180%; }
 div.body h2 { font-size: 150%; }
 div.body h3 { font-size: 130%; }
 div.body h4 { font-size: 110%; }
+/*
+ * Let long headings wrap before they overflow page layout.
+ */
+div.body h1, div.body h2, div.body h3, div.body h4,
+div.body h5, div.body h6 {
+    overflow-wrap: anywhere;
+}
 
 /* toctree captions are styled like h2 */
 div.toctree-wrapper p.caption[role=heading] { font-size: 150%; }
-- 
2.51.0

On 3/21/26 7:48 AM, Rito Rhymes wrote:
> Examples of affected pages on docs.kernel.org this patch improves:
>   userspace-api/gpio/gpio-handle-set-line-values-ioctl.html
>   userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.html
>   userspace-api/gpio/gpio-handle-get-line-values-ioctl.html
>   userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.html
>   userspace-api/gpio/gpio-v2-lineinfo-changed-read.html
>   userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.html
>   userspace-api/gpio/gpio-v2-line-set-config-ioctl.html
>   userspace-api/gpio/gpio-v2-line-get-values-ioctl.html
>   userspace-api/sysfs-platform_profile.html
> 
> Rito Rhymes (1):
>   docs: allow long unbroken headings to wrap and prevent overflow
> 
>  Documentation/sphinx-static/custom.css | 7 +++++++
>  1 file changed, 7 insertions(+)
> 

Some of these (html pages listed above) now split the heading where it
might appear that a split is not needed. Maybe the heading was going past
the "right margin" previously and after the patch it does not do that?

E.g., before the patch I see this heading:
GPIO_V2_LINE_GET_VALUES_IOCTL

After the patch I see:
GPIO_V2_LINE_GET_VALUES_IOCT
L


Regarding the last example that has a problem, that heading just needs
to be fixed. The "(e.g. ...)" part of it shouldn't be in the heading.

To me these 4 patches:
[PATCH 1/1] docs: allow inline literals in paragraphs to wrap to prevent overflow
[PATCH 1/1] docs: allow long unbroken headings to wrap and prevent overflow
[PATCH 1/1] docs: contain horizontal overflow in C API descriptions
[PATCH 1/1] docs: wrap generated tables to contain small-screen overflow

feel inconsistent. In some cases they add horizontal scrolling while in
other cases they add auto-wrapping.
Maybe it's just me, but you might need some more justification for making
the choices in the patches.

However, prior to these patches there was definitely some loss of
characters on the right side, e.g., in C API blocks.

thanks.
-- 
~Randy

Thanks for testing things out and for asking about the logic behind the
implementation choices.

Is there consistency in the solutions chosen?

Those 4 patches are not a single series for a reason. They are targeted
fixes for distinct contexts and use cases where one solution may be
preferable to the other, i.e. wrapping vs. contained horizontal scroll
overflow. They are logically consistent in that the reasons for the
chosen solution do not directly contradict each other across these
contexts, but they should not all be treated as requiring the same
generic behavior, such as wrapping everywhere or contained horizontal
scrolling everywhere. I also did not submit them as a single patch
series because I did not want each patch to have to justify itself
against every other patch as a single thematic unit, because the cases
are very different even if they share an underlying symptom (page-wide
horizontal scroll overflow).

> docs: allow long unbroken headings to wrap and prevent overflow

Why prefer wrapping?

You found an unfortunate edge case, but the core regression this fix
addresses is headings pushing past the right page margin and creating
page-wide horizontal scroll overflow that breaks the page layout
instead of wrapping.

The edge case being:

GPIO_V2_LINE_GET_VALUES_IOCTL

Modern browsers do not treat underscores as natural word-break points.
That whole string is a long unbroken token without a natural breakpoint,
so without the added wrapping behavior it will create page-wide
horizontal overflow on small enough screen sizes, as you can test on the
live site.

So semantically, it looks like a regression to see

GPIO_V2_LINE_GET_VALUES_IOCT
L

instead of:

GPIO_V2_LINE_GET_VALUES_
IOCTL

But that is still the expected browser behavior. It only looks
semantically incorrect because the string has internal structure that
the browser does not understand for wrapping purposes. It is equivalent
to taking a long unbroken string like:

GPIOV2LINEGETVALUESIOCTL

and getting:

GPIOV2LINEGETVALUESIOCT
L

There may be semantically parseable words in there, but regular browser
wrapping does not know that.

So this solution does come with a trade-off.

Long unbroken strings that have semantic shape but no natural
breakpoint, including code-style names, will wrap unnaturally.

But for the majority of headings, wrapping produces clean shapes where
the semantic structure is preserved because there is spacing or a `-`
somewhere in the heading.

For headings, having everything immediately visible without requiring
horizontal scrolling is the preferred trade-off. It is tolerable for
headings to wrap differently across screen sizes, whether that means 1
line, 2 lines, or 3 lines. In most cases, however many lines the
heading wraps to, it remains readable and semantically preserved. I do
not think it would be a reasonable trade-off to introduce contained
horizontal scrolling for headings just to avoid the edge cases
involving long unbroken code-style strings.

Thus, wrapping is the appropriate choice here.

With that said, we could go a step further and add JavaScript to help
treat underscores as wrap points, but I do not think that is ideal. It
would be client-side post-processing, and I do not see similar
non-Sphinx-native JavaScript being used here for this kind of text
shaping. I am open to that if people think it is worth it, but it would
be a new precedent here and not a standard web approach.

> docs: contain horizontal overflow in C API descriptions

Why prefer contained horizontal scroll overflow?

For this patch, contained horizontal scrolling is preferred because
code fidelity is the priority. The code is isolated from the rest of the
page in a dedicated block and presented in a form that is intended to
remain representative of the code itself. Wrapping distorts spacing and
line structure, which affects fidelity, creates misleading renderings,
and reduces readability. Therefore, wrapping is not a good trade-off
here.

> docs: allow inline literals in paragraphs to wrap to prevent overflow

Why prefer wrapping?

If preserving code fidelity were the priority here, the code would not
be embedded inside explanatory prose. The purpose in this context is to
read a paragraph that includes code as part of the explanation, and it
would be distracting and hurt readability if the user needed to scroll
horizontally mid-paragraph just to continue reading. In that context, we
treat it like any other `<span>` inside of a `<p>`.

> docs: wrap generated tables to contain small-screen overflow

Why prefer contained horizontal scroll overflow?

Wrapping is generally not practical here.

Many of these tables, often under a `*/features.html*`, exceed at least
double the viewport width of a mobile screen size. Wrapping the cell
content enough to fit within a small viewport would often create
unreadable vertical stacks of wrapped text. Having the rows or columns
reorganize themselves in some way to fit the viewport would
fundamentally change the table structure and how it is intended to be
navigated, which defeats the simplicity of keeping a single table
structure for many purposes.

The simplest solution is to respect the width the generated table
creates and allow horizontal scrolling within the table container,
without allowing the entire page width to expand.

Hi,

Thanks for the explanations.


On 3/22/26 5:14 AM, Rito Rhymes wrote:
> Thanks for testing things out and for asking about the logic behind the
> implementation choices.
> 
> Is there consistency in the solutions chosen?
> 
> Those 4 patches are not a single series for a reason. They are targeted
> fixes for distinct contexts and use cases where one solution may be
> preferable to the other, i.e. wrapping vs. contained horizontal scroll
> overflow. They are logically consistent in that the reasons for the
> chosen solution do not directly contradict each other across these
> contexts, but they should not all be treated as requiring the same
> generic behavior, such as wrapping everywhere or contained horizontal
> scrolling everywhere. I also did not submit them as a single patch
> series because I did not want each patch to have to justify itself
> against every other patch as a single thematic unit, because the cases
> are very different even if they share an underlying symptom (page-wide
> horizontal scroll overflow).

OK.

>> docs: allow long unbroken headings to wrap and prevent overflow
> 
> Why prefer wrapping?
> 
> You found an unfortunate edge case, but the core regression this fix
> addresses is headings pushing past the right page margin and creating
> page-wide horizontal scroll overflow that breaks the page layout
> instead of wrapping.

Yes, I understand that. And in general the patch is a good idea,
even though I observed that edge case.

> The edge case being:
> 
> GPIO_V2_LINE_GET_VALUES_IOCTL
> 
> Modern browsers do not treat underscores as natural word-break points.
> That whole string is a long unbroken token without a natural breakpoint,
> so without the added wrapping behavior it will create page-wide
> horizontal overflow on small enough screen sizes, as you can test on the
> live site.
> 
> So semantically, it looks like a regression to see
> 
> GPIO_V2_LINE_GET_VALUES_IOCT
> L
> 
> instead of:
> 
> GPIO_V2_LINE_GET_VALUES_
> IOCTL
> 
> But that is still the expected browser behavior. It only looks
> semantically incorrect because the string has internal structure that
> the browser does not understand for wrapping purposes. It is equivalent
> to taking a long unbroken string like:
> 
> GPIOV2LINEGETVALUESIOCTL
> 
> and getting:
> 
> GPIOV2LINEGETVALUESIOCT
> L
> 
> There may be semantically parseable words in there, but regular browser
> wrapping does not know that.
> 
> So this solution does come with a trade-off.

Yes, I wasn't trying to suggest using underscore as a break character.

> Long unbroken strings that have semantic shape but no natural
> breakpoint, including code-style names, will wrap unnaturally.
> 
> But for the majority of headings, wrapping produces clean shapes where
> the semantic structure is preserved because there is spacing or a `-`
> somewhere in the heading.

OK.

> For headings, having everything immediately visible without requiring
> horizontal scrolling is the preferred trade-off. It is tolerable for
> headings to wrap differently across screen sizes, whether that means 1
> line, 2 lines, or 3 lines. In most cases, however many lines the
> heading wraps to, it remains readable and semantically preserved. I do
> not think it would be a reasonable trade-off to introduce contained
> horizontal scrolling for headings just to avoid the edge cases
> involving long unbroken code-style strings.
> 
> Thus, wrapping is the appropriate choice here.

OK, sounds reasonable.

> With that said, we could go a step further and add JavaScript to help
> treat underscores as wrap points, but I do not think that is ideal. It
> would be client-side post-processing, and I do not see similar
> non-Sphinx-native JavaScript being used here for this kind of text
> shaping. I am open to that if people think it is worth it, but it would
> be a new precedent here and not a standard web approach.

nah.

>> docs: contain horizontal overflow in C API descriptions
> 
> Why prefer contained horizontal scroll overflow?
> 
> For this patch, contained horizontal scrolling is preferred because
> code fidelity is the priority. The code is isolated from the rest of the
> page in a dedicated block and presented in a form that is intended to
> remain representative of the code itself. Wrapping distorts spacing and
> line structure, which affects fidelity, creates misleading renderings,
> and reduces readability. Therefore, wrapping is not a good trade-off
> here.

I see.

>> docs: allow inline literals in paragraphs to wrap to prevent overflow
> 
> Why prefer wrapping?
> 
> If preserving code fidelity were the priority here, the code would not
> be embedded inside explanatory prose. The purpose in this context is to
> read a paragraph that includes code as part of the explanation, and it
> would be distracting and hurt readability if the user needed to scroll
> horizontally mid-paragraph just to continue reading. In that context, we
> treat it like any other `<span>` inside of a `<p>`.
> 
>> docs: wrap generated tables to contain small-screen overflow
> 
> Why prefer contained horizontal scroll overflow?
> 
> Wrapping is generally not practical here.
> 
> Many of these tables, often under a `*/features.html*`, exceed at least
> double the viewport width of a mobile screen size. Wrapping the cell
> content enough to fit within a small viewport would often create
> unreadable vertical stacks of wrapped text. Having the rows or columns
> reorganize themselves in some way to fit the viewport would
> fundamentally change the table structure and how it is intended to be
> navigated, which defeats the simplicity of keeping a single table
> structure for many purposes.

Sounds messy.

> The simplest solution is to respect the width the generated table
> creates and allow horizontal scrolling within the table container,
> without allowing the entire page width to expand.

I see that Jon asked about provenance of these patches.
I meant to do that as well but got wrapped up in Advanced Search
testing.

-- 
~Randy

I am glad the reasoning and trade-offs make sense.

I also saw Jon's note on coding-assistant attribution/disclosure
and have already rerolled the relevant patches accordingly.

Rito