[PATCH 0/1] docs: examples of pages affected by C API signature overflow

[PATCH 0/1] docs: examples of pages affected by C API signature overflow

[Rito Rhymes]

Examples of affected pages on docs.kernel.org this patch improves:
  core-api/genalloc.html
  userspace-api/iommufd.html
  userspace-api/liveupdate.html
  core-api/liveupdate.html
  arch/sh/index.html
  arch/x86/sgx.html
  devicetree/kernel-api.html
  userspace-api/fwctl/fwctl-cxl.html
  driver-api/regulator.html
  driver-api/reset.html
  driver-api/s390-drivers.html
  driver-api/scsi.html
  driver-api/spi.html
  driver-api/target.html
  driver-api/wbrf.html
  driver-api/wmi.html

Rito Rhymes (1):
  docs: contain horizontal overflow in C API descriptions

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

-- 
2.51.0

[PATCH 1/1] docs: contain horizontal overflow in C API descriptions

[Rito Rhymes]

Some documentation pages contain long C API signatures that can exceed
the content width and cause page-wide horizontal scroll overflow.

Apply contained horizontal scrolling to C API description blocks and
keep their signature rows on one line. This preserves signature
formatting while preventing them from breaking page layout.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
---
 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..18bf8813b 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -40,6 +40,13 @@ li { text-indent: 0em; }
 dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
 /* indent lines 2+ of multi-line function prototypes */
 dl.function dt { margin-left: 10em; text-indent: -10em; }
+/*
+ * Preserve C API signatures on one line and apply contained horizontal
+ * scrolling to prevent them from exceeding their container width and
+ * breaking page layout.
+ */
+dl.c { overflow-x: auto; overflow-y: hidden; }
+dl.c > dt.sig.sig-object { white-space: nowrap; }
 dt.sig-object { font-size: larger; }
 div.kernelindent { margin-left: 2em; margin-right: 4em; }
 
-- 
2.51.0

Re: [PATCH 1/1] docs: contain horizontal overflow in C API descriptions

[Randy Dunlap]

On 3/21/26 7:25 AM, Rito Rhymes wrote:
> Some documentation pages contain long C API signatures that can exceed
> the content width and cause page-wide horizontal scroll overflow.
> 
> Apply contained horizontal scrolling to C API description blocks and
> keep their signature rows on one line. This preserves signature
> formatting while preventing them from breaking page layout.
> 
> Signed-off-by: Rito Rhymes <rito@ritovision.com>
> ---
>  Documentation/sphinx-static/custom.css | 7 +++++++
>  1 file changed, 7 insertions(+)

Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

[PATCH v2 0/1] docs: examples of pages affected by C API signature overflow

[Rito Rhymes]

Examples of affected pages on docs.kernel.org this patch improves:
  core-api/genalloc.html
  userspace-api/iommufd.html
  userspace-api/liveupdate.html
  core-api/liveupdate.html
  arch/sh/index.html
  arch/x86/sgx.html
  devicetree/kernel-api.html
  userspace-api/fwctl/fwctl-cxl.html
  driver-api/regulator.html
  driver-api/reset.html
  driver-api/s390-drivers.html
  driver-api/scsi.html
  driver-api/spi.html
  driver-api/target.html
  driver-api/wbrf.html
  driver-api/wmi.html

Rito Rhymes (1):
  docs: contain horizontal overflow in C API descriptions

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

-- 
2.51.0

[PATCH v2 1/1] docs: contain horizontal overflow in C API descriptions

[Rito Rhymes]

Some documentation pages contain long C API signatures that can exceed
the content width and cause page-wide horizontal scroll overflow.

Apply contained horizontal scrolling to C API description blocks and
keep their signature rows on one line. This preserves signature
formatting while preventing them from breaking page layout.

Contained horizontal scrolling is preferred over wrapping here because
code fidelity is the priority. These blocks are intended to remain
representative of the code itself. Wrapping distorts spacing and line
structure, which affects fidelity, creates misleading renderings, and
reduces readability.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v2: add Assisted-by attribution and clarify scrolling 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..18bf8813b 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -40,6 +40,13 @@ li { text-indent: 0em; }
 dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
 /* indent lines 2+ of multi-line function prototypes */
 dl.function dt { margin-left: 10em; text-indent: -10em; }
+/*
+ * Preserve C API signatures on one line and apply contained horizontal
+ * scrolling to prevent them from exceeding their container width and
+ * breaking page layout.
+ */
+dl.c { overflow-x: auto; overflow-y: hidden; }
+dl.c > dt.sig.sig-object { white-space: nowrap; }
 dt.sig-object { font-size: larger; }
 div.kernelindent { margin-left: 2em; margin-right: 4em; }
 
-- 
2.51.0

Re: [PATCH v2 0/1] docs: examples of pages affected by C API signature overflow

[Jonathan Corbet]

Rito Rhymes <rito@ritovision.com> writes:

> Examples of affected pages on docs.kernel.org this patch improves:
>   core-api/genalloc.html
>   userspace-api/iommufd.html
>   userspace-api/liveupdate.html
>   core-api/liveupdate.html
>   arch/sh/index.html
>   arch/x86/sgx.html
>   devicetree/kernel-api.html
>   userspace-api/fwctl/fwctl-cxl.html
>   driver-api/regulator.html
>   driver-api/reset.html
>   driver-api/s390-drivers.html
>   driver-api/scsi.html
>   driver-api/spi.html
>   driver-api/target.html
>   driver-api/wbrf.html
>   driver-api/wmi.html
>
> Rito Rhymes (1):
>   docs: contain horizontal overflow in C API descriptions
>
>  Documentation/sphinx-static/custom.css | 7 +++++++
>  1 file changed, 7 insertions(+)

This is a general comment applying to most of the patches you have sent:
is not a typical or particularly helpful cover letter.  The cover letter
tells reviewers what the series as a whole does; this one does not.
Perhaps more to the point, a cover letter is rarely warranted for a
single patch; just put any relevant information into the changelog of
the patch itself.

In this case, some examples of the problem being solved are certainly
warranted, though perhaps not so many as given here.  They should be in
the patch changelog so that somebody wondering, years from now, why the
patch was applied can gain that understanding.

The names of HTML files are perhaps not ideal; since you're talking
about docs.kernel.org in particular, you could give URLs that people
could view directly.  So, for example:

  https://docs.kernel.org/6.19/core-api/genalloc.html

Note the explicit version so that the problem will be findable in the
distant future, even after the fix is applied.

Thanks,

jon

Re: [PATCH v2 0/1] docs: examples of pages affected by C API signature overflow

[Rito Rhymes]

Thank you for the feedback.

I'll put some examples in the changelogs with versioned URLs and
reroll them without a cover letter.

> The cover letter tells reviewers what the series as a whole does

Admittedly, I knew including a cover letter for a single patch was
non-standard. Given the quantity of examples I aimed to include,
I didn't think it acceptable to include it all in the changelog, but I
knew having the examples was important for testing, so I repurposed the
cover letter as the vehicle for including them. I'll lay off that.

> In this case, some examples of the problem being solved are certainly
> warranted, though perhaps not so many as given here.

I'll scale it down to just a few for the rerolls in the patchlogs.

FWIW my rationale was clear:

"Is this issue a significant enough pattern to justify the risk of
regressions and the review bandwidth required to address it?"

^ I thought it was important to preempt that question given the size
of this repo, assuming layout issues aren't exactly top of mind and
that the potential changes may have systemic effects to consider.

I did an audit for each of the layout fixes and resolved that if I
couldn't find 10 instances of an issue, it would not be worthwhile or
defensible to push. As a first-time contributor here, I figured showing
a concrete list of examples I found was preferable to a take-my-word-
for-it description of each issue's scale while showing only 1 or 2
examples.

> The names of HTML files are perhaps not ideal; since you're
> talking about docs.kernel.org in particular, you could give URLs
> that people could view directly.
> So for example
>
> https://docs.kernel.org/6.19/core-api/genalloc.html
>
> Note the explicit version so that the problem will be findable in the
> distant future, even after the fix is applied.

Yeah that approach makes more sense; the versioning anchors the fix
well for future. I had used neutral HTML file names with local user
testing in mind where the canonical domain wouldn't be used now or in
post-fix source trees.

Rito

Re: [PATCH v2 0/1] docs: examples of pages affected by C API signature overflow

[Jonathan Corbet]

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

> Thank you for the feedback.
>
> I'll put some examples in the changelogs with versioned URLs and
> reroll them without a cover letter.
>
>> The cover letter tells reviewers what the series as a whole does
>
> Admittedly, I knew including a cover letter for a single patch was
> non-standard. Given the quantity of examples I aimed to include,
> I didn't think it acceptable to include it all in the changelog, but I
> knew having the examples was important for testing, so I repurposed the
> cover letter as the vehicle for including them. I'll lay off that.

If you want to include extra information for reviewers that doesn't
belong in the changelog, you can put it below the "---" line and it will
be stripped out at application time.

Thanks,

jon

[PATCH v3] docs: contain horizontal overflow in C API descriptions

[Rito Rhymes]

Some documentation pages contain long C API signatures that can exceed
the content width and cause page-wide horizontal scroll overflow.

Apply contained horizontal scrolling to C API description blocks and
keep their signature rows on one line. This preserves signature
formatting while preventing them from breaking page layout.

Contained horizontal scrolling is preferred over wrapping here because
code fidelity is the priority. These blocks are intended to remain
representative of the code itself. Wrapping distorts spacing and line
structure, which affects fidelity, creates misleading renderings, and
reduces readability.

Examples:
  https://docs.kernel.org/6.15/driver-api/regulator.html
  https://docs.kernel.org/6.15/userspace-api/fwctl/fwctl-cxl.html

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v3: add latest public versioned URL examples to the patchlog

 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..18bf8813b 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -40,6 +40,13 @@ li { text-indent: 0em; }
 dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
 /* indent lines 2+ of multi-line function prototypes */
 dl.function dt { margin-left: 10em; text-indent: -10em; }
+/*
+ * Preserve C API signatures on one line and apply contained horizontal
+ * scrolling to prevent them from exceeding their container width and
+ * breaking page layout.
+ */
+dl.c { overflow-x: auto; overflow-y: hidden; }
+dl.c > dt.sig.sig-object { white-space: nowrap; }
 dt.sig-object { font-size: larger; }
 div.kernelindent { margin-left: 2em; margin-right: 4em; }
 
-- 
2.51.0

Re: [PATCH v3] docs: contain horizontal overflow in C API descriptions

[Jonathan Corbet]

Rito Rhymes <rito@ritovision.com> writes:

> Some documentation pages contain long C API signatures that can exceed
> the content width and cause page-wide horizontal scroll overflow.
>
> Apply contained horizontal scrolling to C API description blocks and
> keep their signature rows on one line. This preserves signature
> formatting while preventing them from breaking page layout.
>
> Contained horizontal scrolling is preferred over wrapping here because
> code fidelity is the priority. These blocks are intended to remain
> representative of the code itself. Wrapping distorts spacing and line
> structure, which affects fidelity, creates misleading renderings, and
> reduces readability.
>
> Examples:
>   https://docs.kernel.org/6.15/driver-api/regulator.html
>   https://docs.kernel.org/6.15/userspace-api/fwctl/fwctl-cxl.html
>
> Signed-off-by: Rito Rhymes <rito@ritovision.com>
> Assisted-by: Codex:GPT-5.4
> ---
> v3: add latest public versioned URL examples to the patchlog
>
>  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..18bf8813b 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -40,6 +40,13 @@ li { text-indent: 0em; }
>  dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
>  /* indent lines 2+ of multi-line function prototypes */
>  dl.function dt { margin-left: 10em; text-indent: -10em; }
> +/*
> + * Preserve C API signatures on one line and apply contained horizontal
> + * scrolling to prevent them from exceeding their container width and
> + * breaking page layout.
> + */
> +dl.c { overflow-x: auto; overflow-y: hidden; }
> +dl.c > dt.sig.sig-object { white-space: nowrap; }
>  dt.sig-object { font-size: larger; }

I am not convinced this is the best solution to the problem; somebody
looking at this documentation is going to want to see the prototype, and
reaching over for horizontal scrolling will not be entirely welcome.

I guess, though, that it's better than what we have now, so I have
applied this one.

Thanks,

jon

Re: [PATCH v3] docs: contain horizontal overflow in C API descriptions

[Rito Rhymes]

If you could imagine an optimal solution, what would it look like?
Can you describe the layout and/or behavior?

Maybe I can implement it.

Rito

Re: [PATCH v3] docs: contain horizontal overflow in C API descriptions

[Jonathan Corbet]

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

> If you could imagine an optimal solution, what would it look like?
> Can you describe the layout and/or behavior?

It should wrap so that the entire prototype is visible, but the way that
happens on small screens is definitely ugly.  The trick would be to have
it wrap the way it would for an overly long line in the source.

jon

Re: [PATCH v3] docs: contain horizontal overflow in C API descriptions

[Rito Rhymes]

> It should wrap so that the entire prototype is visible, but the
> way that happens on small screens is definitely ugly. The trick
> would be to have it wrap the way it would for an overly long line
> in the source.

I re-rolled it again to match those specs.

FWIW:
I tackled basically the same issue in Public Inbox; Eric wanted
it the way you described, but he was married to his highly efficent
custom blob rendering system where the approach caused regressions
with no reasonable workaround. And no alternative systems I tried
came close to his system's efficiency even though they fixed the
issue. At the end of the day, page-wide horizontal scroll overflow
turned out to be the best fit solution there.

I think the preserved whitespace wrapping approach should work fine
here though.

I rerolled so you can choose whichever you think is best, though
personally, I think contained horizontal scroll overflow is the
way to go since it provides a more straight-forward awareness of
the code shape without needing to be aware of wrapping distortions.

I leave it to you.

Rito

[PATCH v4] docs: wrap long C API signatures to prevent page overflow

[Rito Rhymes]

Some documentation pages contain long C API signatures that exceed
the content width and cause page-wide horizontal scroll overflow.

Override white-space on inner spans from nowrap to pre-wrap, which
preserves existing whitespace but allows line breaks at space
boundaries. overflow-wrap: anywhere is then applied to the signature
element so that long strings wider than the container can still
wrap where needed.

Examples:
  https://docs.kernel.org/6.15/driver-api/regulator.html
  https://docs.kernel.org/6.15/userspace-api/fwctl/fwctl-cxl.html

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
Assisted-by: Claude:Opus-4.6
---
v4: switch to a whitespace-preserving wrapping approach instead of
    contained horizontal scrolling

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

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..7226be803 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -40,6 +40,12 @@ li { text-indent: 0em; }
 dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
 /* indent lines 2+ of multi-line function prototypes */
 dl.function dt { margin-left: 10em; text-indent: -10em; }
+/*
+ * Wrap long C API signatures the way an overly long source line would
+ * wrap, keeping the entire signature visible without horizontal scroll.
+ */
+dl.c > dt { overflow-wrap: anywhere; }
+dl.c > dt span.pre { white-space: pre-wrap; }
 dt.sig-object { font-size: larger; }
 div.kernelindent { margin-left: 2em; margin-right: 4em; }
 
-- 
2.51.0