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

[Jonathan Corbet]

Rito Rhymes <rito@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx>
> 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